<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
<html>
<head>
<title>Ustr - 1.0.4 reference documentation -- functions</title>
    <style type="text/css">
      A:visited { color: #ff4040; }
      A:hover { color: #20b2aa; }

      P { text-indent: 1em; }

      body     { background: #FFF; color: #000; }

      h2.ind   { background: #DDF; }

      td.title { background: #DFD; }
      td.sect  { background: #DDF; }
      td.obj   { background: #DDD; }

      ul li                       { list-style-type: lower-roman; }
      ul li:hover                 { list-style-type: square; }
      ul:hover li                 { list-style-type: decimal; }
      ul li:hover ul li.obj       { list-style-type: decimal; }
      ul li:hover ul li.obj:hover { list-style-type: square; }
    </style>

  </head>
  <body>
<table width="100%"><tr><td class="title"><h1>Ustr - 1.0.4 reference documentation -- functions (301)</h1>
</td></tr></table><table width="90%"><tr><td>
<h2 class="ind">Index of sections</h2>
<ul>
<li><a href="#indx-Creating_readonly_Ustr_functions">Creating read-only Ustr functions (14)</a>
<li><a href="#indx-Creating_fixed_Ustr_functions">Creating fixed Ustr functions (4)</a>
<li><a href="#indx-Debugging_functions">Debugging functions (12)</a>
<li><a href="#indx-Creating_allocated_Ustr_functions">Creating allocated Ustr functions (28)</a>
<li><a href="#indx-Deleting_a_Ustr_or_data_within_a_Ustr">Deleting a Ustr, or data within a Ustr (8)</a>
<li><a href="#indx-Adding_data_to_a_Ustr">Adding data to a Ustr (8)</a>
<li><a href="#indx-Setting_a_Ustr_to_some_data">Setting a Ustr to some data (9)</a>
<li><a href="#indx-Inserting_data_into_a_Ustr">Inserting data into a Ustr (8)</a>
<li><a href="#indx-Adding_duplicating_and_setting_formatted_data_to_a_Ustr">Adding, duplicating and setting formatted data to a Ustr (26)</a>
<li><a href="#indx-Accessing_the_variables_of_a_Ustr">Accessing the "variables" of a Ustr (16)</a>
<li><a href="#indx-Setting_the_flags_of_a_Ustr">Setting the "flags" of a Ustr (4)</a>
<li><a href="#indx-Comparing_data_in_a_Ustr">Comparing data in a Ustr (36)</a>
<li><a href="#indx-Searching_for_data_in_a_Ustr">Searching for data in a Ustr (20)</a>
<li><a href="#indx-Span_lengths_of_data_in_a_Ustr">Span lengths of data in a Ustr (28)</a>
<li><a href="#indx-Doing_IO_from_or_to_a_Ustr">Doing IO from or to a Ustr (10)</a>
<li><a href="#indx-String_substitutionreplacement">String substitution/replacement (18)</a>
<li><a href="#indx-Splitting_a_Ustr">Splitting a Ustr (6)</a>
<li><a href="#indx-Dealing_with_UTF8_in_a_Ustr">Dealing with UTF-8 in a Ustr (6)</a>
<li><a href="#indx-Parsing_ASCII_integer_numbers_from_a_Ustr">Parsing ASCII integer numbers from a Ustr (10)</a>
<li><a href="#indx-Misc_shortcut_helper_functions_for_Ustrs">Misc shortcut helper functions for Ustrs (18)</a>
<li><a href="#indx-Adding_binary_data_to_a_Ustr">Adding binary data to a Ustr (3)</a>
<li><a href="#indx-Parsing_binary_data_from_a_Ustr">Parsing binary data from a Ustr (3)</a>
<li><a href="#indx-Misc_functions">Misc. functions (2)</a>
<li><a href="#indx-Simple_Ustr_pool_API">Simple Ustr pool API (4)</a></ul>
<h2 class="ind">Index of sections, and their contents</h2>
<ul>
<li><a id="indx-Creating_readonly_Ustr_functions" href="#Creating_readonly_Ustr_functions">Creating read-only Ustr functions</a>
<ul>
<li class="obj"><a href="#USTR">USTR()</a>
<li class="obj"><a href="#USTRP">USTRP()</a>
<li class="obj"><a href="#USTR1">USTR1()</a>
<li class="obj"><a href="#USTR2">USTR2()</a>
<li class="obj"><a href="#USTR4">USTR4()</a>
<li class="obj"><a href="#USTR1_CHK">USTR1_CHK()</a>
<li class="obj"><a href="#USTR2_CHK">USTR2_CHK()</a>
<li class="obj"><a href="#USTR4_CHK">USTR4_CHK()</a>
<li class="obj"><a href="#USTRP1">USTRP1()</a>
<li class="obj"><a href="#USTRP2">USTRP2()</a>
<li class="obj"><a href="#USTRP4">USTRP4()</a>
<li class="obj"><a href="#USTRP1_CHK">USTRP1_CHK()</a>
<li class="obj"><a href="#USTRP2_CHK">USTRP2_CHK()</a>
<li class="obj"><a href="#USTRP4_CHK">USTRP4_CHK()</a>
</ul><li><a id="indx-Creating_fixed_Ustr_functions" href="#Creating_fixed_Ustr_functions">Creating fixed Ustr functions</a>
<ul>
<li class="obj"><a href="#USTR_SIZE_FIXED">USTR_SIZE_FIXED()</a>
<li class="obj"><a href="#ustr_init_fixed">ustr_init_fixed()</a>
<li class="obj"><a href="#USTR_SC_INIT_AUTO">USTR_SC_INIT_AUTO()</a>
<li class="obj"><a href="#USTR_SC_INIT_AUTO_OSTR">USTR_SC_INIT_AUTO_OSTR()</a>
</ul><li><a id="indx-Debugging_functions" href="#Debugging_functions">Debugging functions</a>
<ul>
<li class="obj"><a href="#ustr_assert_valid">ustr_assert_valid()</a>
<li class="obj"><a href="#ustr_assert_valid_subustr">ustr_assert_valid_subustr()</a>
<li class="obj"><a href="#USTR_CNTL_MALLOC_CHECK_BEG">USTR_CNTL_MALLOC_CHECK_BEG()</a>
<li class="obj"><a href="#USTR_CNTL_MALLOC_CHECK_LVL">USTR_CNTL_MALLOC_CHECK_LVL()</a>
<li class="obj"><a href="#USTR_CNTL_MALLOC_CHECK_MEM">USTR_CNTL_MALLOC_CHECK_MEM()</a>
<li class="obj"><a href="#USTR_CNTL_MALLOC_CHECK_MEM_SZ">USTR_CNTL_MALLOC_CHECK_MEM_SZ()</a>
<li class="obj"><a href="#USTR_CNTL_MALLOC_CHECK_MEM_MINSZ">USTR_CNTL_MALLOC_CHECK_MEM_MINSZ()</a>
<li class="obj"><a href="#USTR_CNTL_MALLOC_CHECK_MEM_USTR">USTR_CNTL_MALLOC_CHECK_MEM_USTR()</a>
<li class="obj"><a href="#USTR_CNTL_MALLOC_CHECK_MEM_USTRP">USTR_CNTL_MALLOC_CHECK_MEM_USTRP()</a>
<li class="obj"><a href="#USTR_CNTL_MALLOC_CHECK_END">USTR_CNTL_MALLOC_CHECK_END()</a>
<li class="obj"><a href="#USTR_CNTL_MALLOC_CHECK_ADD">USTR_CNTL_MALLOC_CHECK_ADD()</a>
<li class="obj"><a href="#USTR_CNTL_MALLOC_CHECK_DEL">USTR_CNTL_MALLOC_CHECK_DEL()</a>
</ul><li><a id="indx-Creating_allocated_Ustr_functions" href="#Creating_allocated_Ustr_functions">Creating allocated Ustr functions</a>
<ul>
<li class="obj"><a href="#ustr_init_size">ustr_init_size()</a>
<li class="obj"><a href="#ustr_init_alloc">ustr_init_alloc()</a>
<li class="obj"><a href="#ustr_dupx_empty">ustr_dupx_empty()</a>
<li class="obj"><a href="#ustr_dup_empty">ustr_dup_empty()</a>
<li class="obj"><a href="#ustr_dupx_undef">ustr_dupx_undef()</a>
<li class="obj"><a href="#ustr_dup_undef">ustr_dup_undef()</a>
<li class="obj"><a href="#ustr_dup">ustr_dup()</a>
<li class="obj"><a href="#ustr_dupx">ustr_dupx()</a>
<li class="obj"><a href="#ustr_sc_dup">ustr_sc_dup()</a>
<li class="obj"><a href="#ustr_sc_dupx">ustr_sc_dupx()</a>
<li class="obj"><a href="#ustr_dup_buf">ustr_dup_buf()</a>
<li class="obj"><a href="#ustr_dupx_buf">ustr_dupx_buf()</a>
<li class="obj"><a href="#ustr_dup_cstr">ustr_dup_cstr()</a>
<li class="obj"><a href="#ustr_dupx_cstr">ustr_dupx_cstr()</a>
<li class="obj"><a href="#USTR_DUP_OSTR">USTR_DUP_OSTR()</a>
<li class="obj"><a href="#USTR_DUP_OBJ">USTR_DUP_OBJ()</a>
<li class="obj"><a href="#ustr_dup_subustr">ustr_dup_subustr()</a>
<li class="obj"><a href="#ustr_dupx_subustr">ustr_dupx_subustr()</a>
<li class="obj"><a href="#ustr_dup_rep_chr">ustr_dup_rep_chr()</a>
<li class="obj"><a href="#ustr_dupx_rep_chr">ustr_dupx_rep_chr()</a>
<li class="obj"><a href="#ustr_sc_vjoin">ustr_sc_vjoin()</a>
<li class="obj"><a href="#ustr_sc_join">ustr_sc_join()</a>
<li class="obj"><a href="#ustr_sc_vjoinx">ustr_sc_vjoinx()</a>
<li class="obj"><a href="#ustr_sc_joinx">ustr_sc_joinx()</a>
<li class="obj"><a href="#ustr_sc_vconcat">ustr_sc_vconcat()</a>
<li class="obj"><a href="#ustr_sc_concat">ustr_sc_concat()</a>
<li class="obj"><a href="#ustr_sc_vconcatx">ustr_sc_vconcatx()</a>
<li class="obj"><a href="#ustr_sc_concatx">ustr_sc_concatx()</a>
</ul><li><a id="indx-Deleting_a_Ustr_or_data_within_a_Ustr" href="#Deleting_a_Ustr_or_data_within_a_Ustr">Deleting a Ustr, or data within a Ustr</a>
<ul>
<li class="obj"><a href="#ustr_free">ustr_free()</a>
<li class="obj"><a href="#ustrp_free">ustrp_free()</a>
<li class="obj"><a href="#ustr_sc_free">ustr_sc_free()</a>
<li class="obj"><a href="#ustr_sc_free2">ustr_sc_free2()</a>
<li class="obj"><a href="#ustr_sc_free_shared">ustr_sc_free_shared()</a>
<li class="obj"><a href="#ustr_del">ustr_del()</a>
<li class="obj"><a href="#ustr_del_subustr">ustr_del_subustr()</a>
<li class="obj"><a href="#ustr_sc_del">ustr_sc_del()</a>
</ul><li><a id="indx-Adding_data_to_a_Ustr" href="#Adding_data_to_a_Ustr">Adding data to a Ustr</a>
<ul>
<li class="obj"><a href="#ustr_add_undef">ustr_add_undef()</a>
<li class="obj"><a href="#ustr_add_buf">ustr_add_buf()</a>
<li class="obj"><a href="#ustr_add_cstr">ustr_add_cstr()</a>
<li class="obj"><a href="#USTR_ADD_OSTR">USTR_ADD_OSTR()</a>
<li class="obj"><a href="#USTR_ADD_OBJ">USTR_ADD_OBJ()</a>
<li class="obj"><a href="#ustr_add">ustr_add()</a>
<li class="obj"><a href="#ustr_add_subustr">ustr_add_subustr()</a>
<li class="obj"><a href="#ustr_add_rep_chr">ustr_add_rep_chr()</a>
</ul><li><a id="indx-Setting_a_Ustr_to_some_data" href="#Setting_a_Ustr_to_some_data">Setting a Ustr to some data</a>
<ul>
<li class="obj"><a href="#ustr_set_undef">ustr_set_undef()</a>
<li class="obj"><a href="#ustr_set_empty">ustr_set_empty()</a>
<li class="obj"><a href="#ustr_set_buf">ustr_set_buf()</a>
<li class="obj"><a href="#ustr_set_cstr">ustr_set_cstr()</a>
<li class="obj"><a href="#USTR_SET_OSTR">USTR_SET_OSTR()</a>
<li class="obj"><a href="#USTR_SET_OBJ">USTR_SET_OBJ()</a>
<li class="obj"><a href="#ustr_set">ustr_set()</a>
<li class="obj"><a href="#ustr_set_subustr">ustr_set_subustr()</a>
<li class="obj"><a href="#ustr_set_rep_chr">ustr_set_rep_chr()</a>
</ul><li><a id="indx-Inserting_data_into_a_Ustr" href="#Inserting_data_into_a_Ustr">Inserting data into a Ustr</a>
<ul>
<li class="obj"><a href="#ustr_ins_undef">ustr_ins_undef()</a>
<li class="obj"><a href="#ustr_ins_buf">ustr_ins_buf()</a>
<li class="obj"><a href="#ustr_ins_cstr">ustr_ins_cstr()</a>
<li class="obj"><a href="#USTR_INS_OSTR">USTR_INS_OSTR()</a>
<li class="obj"><a href="#USTR_INS_OBJ">USTR_INS_OBJ()</a>
<li class="obj"><a href="#ustr_ins">ustr_ins()</a>
<li class="obj"><a href="#ustr_ins_subustr">ustr_ins_subustr()</a>
<li class="obj"><a href="#ustr_ins_rep_chr">ustr_ins_rep_chr()</a>
</ul><li><a id="indx-Adding_duplicating_and_setting_formatted_data_to_a_Ustr" href="#Adding_duplicating_and_setting_formatted_data_to_a_Ustr">Adding, duplicating and setting formatted data to a Ustr</a>
<ul>
<li class="obj"><a href="#ustr_add_vfmt_lim">ustr_add_vfmt_lim()</a>
<li class="obj"><a href="#ustr_add_vfmt">ustr_add_vfmt()</a>
<li class="obj"><a href="#ustr_add_fmt_lim">ustr_add_fmt_lim()</a>
<li class="obj"><a href="#ustr_add_fmt">ustr_add_fmt()</a>
<li class="obj"><a href="#ustr_dup_vfmt_lim">ustr_dup_vfmt_lim()</a>
<li class="obj"><a href="#ustr_dup_vfmt">ustr_dup_vfmt()</a>
<li class="obj"><a href="#ustr_dup_fmt_lim">ustr_dup_fmt_lim()</a>
<li class="obj"><a href="#ustr_dup_fmt">ustr_dup_fmt()</a>
<li class="obj"><a href="#ustr_dupx_fmt_lim">ustr_dupx_fmt_lim()</a>
<li class="obj"><a href="#ustr_dupx_fmt">ustr_dupx_fmt()</a>
<li class="obj"><a href="#ustr_set_vfmt_lim">ustr_set_vfmt_lim()</a>
<li class="obj"><a href="#ustr_set_vfmt">ustr_set_vfmt()</a>
<li class="obj"><a href="#ustr_set_fmt_lim">ustr_set_fmt_lim()</a>
<li class="obj"><a href="#ustr_set_fmt">ustr_set_fmt()</a>
<li class="obj"><a href="#ustr_ins_vfmt_lim">ustr_ins_vfmt_lim()</a>
<li class="obj"><a href="#ustr_ins_vfmt">ustr_ins_vfmt()</a>
<li class="obj"><a href="#ustr_ins_fmt_lim">ustr_ins_fmt_lim()</a>
<li class="obj"><a href="#ustr_ins_fmt">ustr_ins_fmt()</a>
<li class="obj"><a href="#ustr_sub_vfmt_lim">ustr_sub_vfmt_lim()</a>
<li class="obj"><a href="#ustr_sub_vfmt">ustr_sub_vfmt()</a>
<li class="obj"><a href="#ustr_sub_fmt_lim">ustr_sub_fmt_lim()</a>
<li class="obj"><a href="#ustr_sub_fmt">ustr_sub_fmt()</a>
<li class="obj"><a href="#ustr_sc_sub_vfmt_lim">ustr_sc_sub_vfmt_lim()</a>
<li class="obj"><a href="#ustr_sc_sub_vfmt">ustr_sc_sub_vfmt()</a>
<li class="obj"><a href="#ustr_sc_sub_fmt_lim">ustr_sc_sub_fmt_lim()</a>
<li class="obj"><a href="#ustr_sc_sub_fmt">ustr_sc_sub_fmt()</a>
</ul><li><a id="indx-Accessing_the_variables_of_a_Ustr" href="#Accessing_the_variables_of_a_Ustr">Accessing the "variables" of a Ustr</a>
<ul>
<li class="obj"><a href="#ustr_len">ustr_len()</a>
<li class="obj"><a href="#ustr_cstr">ustr_cstr()</a>
<li class="obj"><a href="#ustr_wstr">ustr_wstr()</a>
<li class="obj"><a href="#ustr_alloc">ustr_alloc()</a>
<li class="obj"><a href="#ustr_exact">ustr_exact()</a>
<li class="obj"><a href="#ustr_sized">ustr_sized()</a>
<li class="obj"><a href="#ustr_ro">ustr_ro()</a>
<li class="obj"><a href="#ustr_fixed">ustr_fixed()</a>
<li class="obj"><a href="#ustr_enomem">ustr_enomem()</a>
<li class="obj"><a href="#ustr_shared">ustr_shared()</a>
<li class="obj"><a href="#ustr_limited">ustr_limited()</a>
<li class="obj"><a href="#ustr_owner">ustr_owner()</a>
<li class="obj"><a href="#ustr_size">ustr_size()</a>
<li class="obj"><a href="#ustr_size_alloc">ustr_size_alloc()</a>
<li class="obj"><a href="#ustr_size_overhead">ustr_size_overhead()</a>
<li class="obj"><a href="#ustr_conf">ustr_conf()</a>
</ul><li><a id="indx-Setting_the_flags_of_a_Ustr" href="#Setting_the_flags_of_a_Ustr">Setting the "flags" of a Ustr</a>
<ul>
<li class="obj"><a href="#ustr_setf_enomem_err">ustr_setf_enomem_err()</a>
<li class="obj"><a href="#ustr_setf_enomem_clr">ustr_setf_enomem_clr()</a>
<li class="obj"><a href="#ustr_setf_share">ustr_setf_share()</a>
<li class="obj"><a href="#ustr_setf_owner">ustr_setf_owner()</a>
</ul><li><a id="indx-Comparing_data_in_a_Ustr" href="#Comparing_data_in_a_Ustr">Comparing data in a Ustr</a>
<ul>
<li class="obj"><a href="#ustr_cmp_buf">ustr_cmp_buf()</a>
<li class="obj"><a href="#ustr_cmp">ustr_cmp()</a>
<li class="obj"><a href="#ustr_cmp_subustr">ustr_cmp_subustr()</a>
<li class="obj"><a href="#ustr_cmp_cstr">ustr_cmp_cstr()</a>
<li class="obj"><a href="#ustr_cmp_fast_buf">ustr_cmp_fast_buf()</a>
<li class="obj"><a href="#ustr_cmp_fast">ustr_cmp_fast()</a>
<li class="obj"><a href="#ustr_cmp_fast_subustr">ustr_cmp_fast_subustr()</a>
<li class="obj"><a href="#ustr_cmp_fast_cstr">ustr_cmp_fast_cstr()</a>
<li class="obj"><a href="#ustr_cmp_case_buf">ustr_cmp_case_buf()</a>
<li class="obj"><a href="#ustr_cmp_case">ustr_cmp_case()</a>
<li class="obj"><a href="#ustr_cmp_case_subustr">ustr_cmp_case_subustr()</a>
<li class="obj"><a href="#ustr_cmp_case_cstr">ustr_cmp_case_cstr()</a>
<li class="obj"><a href="#ustr_cmp_eq">ustr_cmp_eq()</a>
<li class="obj"><a href="#ustr_cmp_buf_eq">ustr_cmp_buf_eq()</a>
<li class="obj"><a href="#ustr_cmp_subustr_eq">ustr_cmp_subustr_eq()</a>
<li class="obj"><a href="#ustr_cmp_cstr_eq">ustr_cmp_cstr_eq()</a>
<li class="obj"><a href="#ustr_cmp_case_eq">ustr_cmp_case_eq()</a>
<li class="obj"><a href="#ustr_cmp_case_buf_eq">ustr_cmp_case_buf_eq()</a>
<li class="obj"><a href="#ustr_cmp_case_subustr_eq">ustr_cmp_case_subustr_eq()</a>
<li class="obj"><a href="#ustr_cmp_case_cstr_eq">ustr_cmp_case_cstr_eq()</a>
<li class="obj"><a href="#ustr_cmp_prefix_eq">ustr_cmp_prefix_eq()</a>
<li class="obj"><a href="#ustr_cmp_prefix_buf_eq">ustr_cmp_prefix_buf_eq()</a>
<li class="obj"><a href="#ustr_cmp_prefix_cstr_eq">ustr_cmp_prefix_cstr_eq()</a>
<li class="obj"><a href="#ustr_cmp_prefix_subustr_eq">ustr_cmp_prefix_subustr_eq()</a>
<li class="obj"><a href="#ustr_cmp_case_prefix_eq">ustr_cmp_case_prefix_eq()</a>
<li class="obj"><a href="#ustr_cmp_case_prefix_buf_eq">ustr_cmp_case_prefix_buf_eq()</a>
<li class="obj"><a href="#ustr_cmp_case_prefix_cstr_eq">ustr_cmp_case_prefix_cstr_eq()</a>
<li class="obj"><a href="#ustr_cmp_case_prefix_subustr_eq">ustr_cmp_case_prefix_subustr_eq()</a>
<li class="obj"><a href="#ustr_cmp_suffix_eq">ustr_cmp_suffix_eq()</a>
<li class="obj"><a href="#ustr_cmp_suffix_buf_eq">ustr_cmp_suffix_buf_eq()</a>
<li class="obj"><a href="#ustr_cmp_suffix_cstr_eq">ustr_cmp_suffix_cstr_eq()</a>
<li class="obj"><a href="#ustr_cmp_suffix_subustr_eq">ustr_cmp_suffix_subustr_eq()</a>
<li class="obj"><a href="#ustr_cmp_case_suffix_eq">ustr_cmp_case_suffix_eq()</a>
<li class="obj"><a href="#ustr_cmp_case_suffix_buf_eq">ustr_cmp_case_suffix_buf_eq()</a>
<li class="obj"><a href="#ustr_cmp_case_suffix_cstr_eq">ustr_cmp_case_suffix_cstr_eq()</a>
<li class="obj"><a href="#ustr_cmp_case_suffix_subustr_eq">ustr_cmp_case_suffix_subustr_eq()</a>
</ul><li><a id="indx-Searching_for_data_in_a_Ustr" href="#Searching_for_data_in_a_Ustr">Searching for data in a Ustr</a>
<ul>
<li class="obj"><a href="#ustr_srch_chr_fwd">ustr_srch_chr_fwd()</a>
<li class="obj"><a href="#ustr_srch_chr_rev">ustr_srch_chr_rev()</a>
<li class="obj"><a href="#ustr_srch_buf_fwd">ustr_srch_buf_fwd()</a>
<li class="obj"><a href="#ustr_srch_buf_rev">ustr_srch_buf_rev()</a>
<li class="obj"><a href="#ustr_srch_fwd">ustr_srch_fwd()</a>
<li class="obj"><a href="#ustr_srch_rev">ustr_srch_rev()</a>
<li class="obj"><a href="#ustr_srch_cstr_fwd">ustr_srch_cstr_fwd()</a>
<li class="obj"><a href="#ustr_srch_cstr_rev">ustr_srch_cstr_rev()</a>
<li class="obj"><a href="#ustr_srch_subustr_fwd">ustr_srch_subustr_fwd()</a>
<li class="obj"><a href="#ustr_srch_subustr_rev">ustr_srch_subustr_rev()</a>
<li class="obj"><a href="#ustr_srch_case_chr_fwd">ustr_srch_case_chr_fwd()</a>
<li class="obj"><a href="#ustr_srch_case_chr_rev">ustr_srch_case_chr_rev()</a>
<li class="obj"><a href="#ustr_srch_case_buf_fwd">ustr_srch_case_buf_fwd()</a>
<li class="obj"><a href="#ustr_srch_case_buf_rev">ustr_srch_case_buf_rev()</a>
<li class="obj"><a href="#ustr_srch_case_fwd">ustr_srch_case_fwd()</a>
<li class="obj"><a href="#ustr_srch_case_rev">ustr_srch_case_rev()</a>
<li class="obj"><a href="#ustr_srch_case_cstr_fwd">ustr_srch_case_cstr_fwd()</a>
<li class="obj"><a href="#ustr_srch_case_cstr_rev">ustr_srch_case_cstr_rev()</a>
<li class="obj"><a href="#ustr_srch_case_subustr_fwd">ustr_srch_case_subustr_fwd()</a>
<li class="obj"><a href="#ustr_srch_case_subustr_rev">ustr_srch_case_subustr_rev()</a>
</ul><li><a id="indx-Span_lengths_of_data_in_a_Ustr" href="#Span_lengths_of_data_in_a_Ustr">Span lengths of data in a Ustr</a>
<ul>
<li class="obj"><a href="#ustr_spn_chr_fwd">ustr_spn_chr_fwd()</a>
<li class="obj"><a href="#ustr_spn_chr_rev">ustr_spn_chr_rev()</a>
<li class="obj"><a href="#ustr_spn_chrs_fwd">ustr_spn_chrs_fwd()</a>
<li class="obj"><a href="#ustr_spn_chrs_rev">ustr_spn_chrs_rev()</a>
<li class="obj"><a href="#ustr_spn_fwd">ustr_spn_fwd()</a>
<li class="obj"><a href="#ustr_spn_rev">ustr_spn_rev()</a>
<li class="obj"><a href="#ustr_spn_cstr_fwd">ustr_spn_cstr_fwd()</a>
<li class="obj"><a href="#ustr_spn_cstr_rev">ustr_spn_cstr_rev()</a>
<li class="obj"><a href="#ustr_cspn_chr_fwd">ustr_cspn_chr_fwd()</a>
<li class="obj"><a href="#ustr_cspn_chr_rev">ustr_cspn_chr_rev()</a>
<li class="obj"><a href="#ustr_cspn_chrs_fwd">ustr_cspn_chrs_fwd()</a>
<li class="obj"><a href="#ustr_cspn_chrs_rev">ustr_cspn_chrs_rev()</a>
<li class="obj"><a href="#ustr_cspn_fwd">ustr_cspn_fwd()</a>
<li class="obj"><a href="#ustr_cspn_rev">ustr_cspn_rev()</a>
<li class="obj"><a href="#ustr_cspn_cstr_fwd">ustr_cspn_cstr_fwd()</a>
<li class="obj"><a href="#ustr_cspn_cstr_rev">ustr_cspn_cstr_rev()</a>
<li class="obj"><a href="#ustr_utf8_spn_chrs_fwd">ustr_utf8_spn_chrs_fwd()</a>
<li class="obj"><a href="#ustr_utf8_spn_chrs_rev">ustr_utf8_spn_chrs_rev()</a>
<li class="obj"><a href="#ustr_utf8_spn_fwd">ustr_utf8_spn_fwd()</a>
<li class="obj"><a href="#ustr_utf8_spn_rev">ustr_utf8_spn_rev()</a>
<li class="obj"><a href="#ustr_utf8_spn_cstr_fwd">ustr_utf8_spn_cstr_fwd()</a>
<li class="obj"><a href="#ustr_utf8_spn_cstr_rev">ustr_utf8_spn_cstr_rev()</a>
<li class="obj"><a href="#ustr_utf8_cspn_chrs_fwd">ustr_utf8_cspn_chrs_fwd()</a>
<li class="obj"><a href="#ustr_utf8_cspn_chrs_rev">ustr_utf8_cspn_chrs_rev()</a>
<li class="obj"><a href="#ustr_utf8_cspn_fwd">ustr_utf8_cspn_fwd()</a>
<li class="obj"><a href="#ustr_utf8_cspn_rev">ustr_utf8_cspn_rev()</a>
<li class="obj"><a href="#ustr_utf8_cspn_cstr_fwd">ustr_utf8_cspn_cstr_fwd()</a>
<li class="obj"><a href="#ustr_utf8_cspn_cstr_rev">ustr_utf8_cspn_cstr_rev()</a>
</ul><li><a id="indx-Doing_IO_from_or_to_a_Ustr" href="#Doing_IO_from_or_to_a_Ustr">Doing IO from or to a Ustr</a>
<ul>
<li class="obj"><a href="#ustr_io_get">ustr_io_get()</a>
<li class="obj"><a href="#ustr_io_getfile">ustr_io_getfile()</a>
<li class="obj"><a href="#ustr_io_getfilename">ustr_io_getfilename()</a>
<li class="obj"><a href="#ustr_io_getdelim">ustr_io_getdelim()</a>
<li class="obj"><a href="#ustr_io_getline">ustr_io_getline()</a>
<li class="obj"><a href="#ustr_io_put">ustr_io_put()</a>
<li class="obj"><a href="#ustr_io_putline">ustr_io_putline()</a>
<li class="obj"><a href="#ustr_io_putfile">ustr_io_putfile()</a>
<li class="obj"><a href="#ustr_io_putfileline">ustr_io_putfileline()</a>
<li class="obj"><a href="#ustr_io_putfilename">ustr_io_putfilename()</a>
</ul><li><a id="indx-String_substitutionreplacement" href="#String_substitutionreplacement">String substitution/replacement</a>
<ul>
<li class="obj"><a href="#ustr_sub_undef">ustr_sub_undef()</a>
<li class="obj"><a href="#ustr_sub_buf">ustr_sub_buf()</a>
<li class="obj"><a href="#ustr_sub_cstr">ustr_sub_cstr()</a>
<li class="obj"><a href="#USTR_SUB_OSTR">USTR_SUB_OSTR()</a>
<li class="obj"><a href="#USTR_SUB_OBJ">USTR_SUB_OBJ()</a>
<li class="obj"><a href="#ustr_sub">ustr_sub()</a>
<li class="obj"><a href="#ustr_sub_subustr">ustr_sub_subustr()</a>
<li class="obj"><a href="#ustr_sc_sub_undef">ustr_sc_sub_undef()</a>
<li class="obj"><a href="#ustr_sc_sub_buf">ustr_sc_sub_buf()</a>
<li class="obj"><a href="#ustr_sc_sub_cstr">ustr_sc_sub_cstr()</a>
<li class="obj"><a href="#ustr_sc_sub">ustr_sc_sub()</a>
<li class="obj"><a href="#ustr_sc_sub_subustr">ustr_sc_sub_subustr()</a>
<li class="obj"><a href="#USTR_SC_SUB_OSTR">USTR_SC_SUB_OSTR()</a>
<li class="obj"><a href="#USTR_SC_SUB_OBJ">USTR_SC_SUB_OBJ()</a>
<li class="obj"><a href="#ustr_replace_buf">ustr_replace_buf()</a>
<li class="obj"><a href="#ustr_replace_cstr">ustr_replace_cstr()</a>
<li class="obj"><a href="#ustr_replace">ustr_replace()</a>
<li class="obj"><a href="#ustr_replace_rep_chr">ustr_replace_rep_chr()</a>
</ul><li><a id="indx-Splitting_a_Ustr" href="#Splitting_a_Ustr">Splitting a Ustr</a>
<ul>
<li class="obj"><a href="#ustr_split_buf">ustr_split_buf()</a>
<li class="obj"><a href="#ustr_split">ustr_split()</a>
<li class="obj"><a href="#ustr_split_cstr">ustr_split_cstr()</a>
<li class="obj"><a href="#ustr_split_spn_chrs">ustr_split_spn_chrs()</a>
<li class="obj"><a href="#ustr_split_spn_cstr">ustr_split_spn_cstr()</a>
<li class="obj"><a href="#ustr_split_spn">ustr_split_spn()</a>
</ul><li><a id="indx-Dealing_with_UTF8_in_a_Ustr" href="#Dealing_with_UTF8_in_a_Ustr">Dealing with UTF-8 in a Ustr</a>
<ul>
<li class="obj"><a href="#ustr_utf8_valid">ustr_utf8_valid()</a>
<li class="obj"><a href="#ustr_utf8_len">ustr_utf8_len()</a>
<li class="obj"><a href="#ustr_utf8_width">ustr_utf8_width()</a>
<li class="obj"><a href="#ustr_utf8_chars2bytes">ustr_utf8_chars2bytes()</a>
<li class="obj"><a href="#ustr_utf8_bytes2chars">ustr_utf8_bytes2chars()</a>
<li class="obj"><a href="#ustr_sc_utf8_reverse">ustr_sc_utf8_reverse()</a>
</ul><li><a id="indx-Parsing_ASCII_integer_numbers_from_a_Ustr" href="#Parsing_ASCII_integer_numbers_from_a_Ustr">Parsing ASCII integer numbers from a Ustr</a>
<ul>
<li class="obj"><a href="#ustr_parse_uintmaxx">ustr_parse_uintmaxx()</a>
<li class="obj"><a href="#ustr_parse_uintmax">ustr_parse_uintmax()</a>
<li class="obj"><a href="#ustr_parse_intmax">ustr_parse_intmax()</a>
<li class="obj"><a href="#ustr_parse_ulongx">ustr_parse_ulongx()</a>
<li class="obj"><a href="#ustr_parse_ulong">ustr_parse_ulong()</a>
<li class="obj"><a href="#ustr_parse_long">ustr_parse_long()</a>
<li class="obj"><a href="#ustr_parse_uint">ustr_parse_uint()</a>
<li class="obj"><a href="#ustr_parse_int">ustr_parse_int()</a>
<li class="obj"><a href="#ustr_parse_ushort">ustr_parse_ushort()</a>
<li class="obj"><a href="#ustr_parse_short">ustr_parse_short()</a>
</ul><li><a id="indx-Misc_shortcut_helper_functions_for_Ustrs" href="#Misc_shortcut_helper_functions_for_Ustrs">Misc shortcut helper functions for Ustrs</a>
<ul>
<li class="obj"><a href="#ustr_sc_ensure_owner">ustr_sc_ensure_owner()</a>
<li class="obj"><a href="#ustr_sc_wstr">ustr_sc_wstr()</a>
<li class="obj"><a href="#ustr_sc_export_subustr">ustr_sc_export_subustr()</a>
<li class="obj"><a href="#ustr_sc_export">ustr_sc_export()</a>
<li class="obj"><a href="#ustrp_sc_export_subustrp">ustrp_sc_export_subustrp()</a>
<li class="obj"><a href="#ustrp_sc_export">ustrp_sc_export()</a>
<li class="obj"><a href="#ustr_sc_reverse">ustr_sc_reverse()</a>
<li class="obj"><a href="#ustr_sc_tolower">ustr_sc_tolower()</a>
<li class="obj"><a href="#ustr_sc_toupper">ustr_sc_toupper()</a>
<li class="obj"><a href="#ustr_sc_ltrim_chrs">ustr_sc_ltrim_chrs()</a>
<li class="obj"><a href="#ustr_sc_ltrim">ustr_sc_ltrim()</a>
<li class="obj"><a href="#ustr_sc_ltrim_cstr">ustr_sc_ltrim_cstr()</a>
<li class="obj"><a href="#ustr_sc_rtrim_chrs">ustr_sc_rtrim_chrs()</a>
<li class="obj"><a href="#ustr_sc_rtrim">ustr_sc_rtrim()</a>
<li class="obj"><a href="#ustr_sc_rtrim_cstr">ustr_sc_rtrim_cstr()</a>
<li class="obj"><a href="#ustr_sc_trim_chrs">ustr_sc_trim_chrs()</a>
<li class="obj"><a href="#ustr_sc_trim">ustr_sc_trim()</a>
<li class="obj"><a href="#ustr_sc_trim_cstr">ustr_sc_trim_cstr()</a>
</ul><li><a id="indx-Adding_binary_data_to_a_Ustr" href="#Adding_binary_data_to_a_Ustr">Adding binary data to a Ustr</a>
<ul>
<li class="obj"><a href="#ustr_add_b_uint16">ustr_add_b_uint16()</a>
<li class="obj"><a href="#ustr_add_b_uint32">ustr_add_b_uint32()</a>
<li class="obj"><a href="#ustr_add_b_uint64">ustr_add_b_uint64()</a>
</ul><li><a id="indx-Parsing_binary_data_from_a_Ustr" href="#Parsing_binary_data_from_a_Ustr">Parsing binary data from a Ustr</a>
<ul>
<li class="obj"><a href="#ustr_parse_b_uint16">ustr_parse_b_uint16()</a>
<li class="obj"><a href="#ustr_parse_b_uint32">ustr_parse_b_uint32()</a>
<li class="obj"><a href="#ustr_parse_b_uint64">ustr_parse_b_uint64()</a>
</ul><li><a id="indx-Misc_functions" href="#Misc_functions">Misc. functions</a>
<ul>
<li class="obj"><a href="#ustr_realloc">ustr_realloc()</a>
<li class="obj"><a href="#ustr_cntl_opt">ustr_cntl_opt()</a>
</ul><li><a id="indx-Simple_Ustr_pool_API" href="#Simple_Ustr_pool_API">Simple Ustr pool API</a>
<ul>
<li class="obj"><a href="#ustr_pool_ll_make">ustr_pool_ll_make()</a>
<li class="obj"><a href="#ustr_pool_make_subpool">ustr_pool_make_subpool()</a>
<li class="obj"><a href="#ustr_pool_free">ustr_pool_free()</a>
<li class="obj"><a href="#ustr_pool_clear">ustr_pool_clear()</a>
</ul></ul>
</td></tr></table><table width="90%"><tr><td class="sect"><h2><a id="Creating%20read%2donly%20Ustr%20functions">Creating read-only Ustr functions</a></h2>
</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="USTR">USTR()</a>
<br>Returns: <a href="design.html">Ustr string</a><br>Type: struct Ustr *
</td></tr><tr><td>Parameter<strong>[1]</strong>: Pointer to Ustr data<br>Type<strong>[1]</strong>: void *
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This macro function is normally used with the empty string &quot;&quot;.

</td></tr><tr><td><strong>Note:</strong></td></tr><tr><td><p>
</p><p>  There is basically just a simple cast behind the macro.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="USTRP">USTRP()</a>
<br>Returns: <a href="design.html">Ustrp string</a><br>Type: struct Ustrp *
</td></tr><tr><td>Parameter<strong>[1]</strong>: Pointer to Ustrp data<br>Type<strong>[1]</strong>: void *
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This macro function is normally used with the empty string &quot;&quot;.

</td></tr><tr><td><strong>Note:</strong></td></tr><tr><td><p>
</p><p>  There is basically just a simple cast behind the macro.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="USTR1">USTR1()</a>
<br>Returns: <a href="design.html">Ustr string</a><br>Type: struct Ustr *
</td></tr><tr><td>Parameter<strong>[1]</strong>: Encoded number of the length of <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: symbol
</td></tr><tr><td>Parameter<strong>[2]</strong>: Data for <a href="design.html">Ustr string</a><br>Type<strong>[2]</strong>: const char[]
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This macro function simplifies the creation of read-only <a href="design.html">Ustr string</a>'s. And
 is normally used like...
</p><pre>
  USTR1(\x4, "abcd")

</pre><p> ...it is worth pointing out that running with debugging turned on
 (<a href="constants.html#USTR_CONF_USE_ASSERT">USTR_CONF_USE_ASSERT</a>) will complain if the length isn't encoded correctly, as
 in...
</p><pre>
  USTR1(\x3, "abcd")

</pre><p> ...here <a href="functions.html#ustr_assert_valid">ustr_assert_valid()</a> will fail, which is called before most functions do
 anything in debugging mode. Note also that extra debugging
 (<a href="constants.html#USTR_CONF_USE_EOS_MARK">USTR_CONF_USE_EOS_MARK</a>) will still catch cases like...
</p><pre>
  USTR1(\x3, "abc\0d")

</pre><p> ...at least using debugging is esp. important if you are putting UTF-8
 characters into the strings.

</td></tr><tr><td><strong>Note:</strong></td></tr><tr><td><p>
</p><p>  Having <a href="functions.html#ustr_ro">ustr_ro()</a> return true means that the Ustr cannot be written to without
 be reallocated into allocation space ... not that <a href="functions.html#ustr_add">ustr_add()</a> etc. will fail.
</p><p>  There is now USTR1_CHK() which performs a compile time check so you can never
 have an invalid ustr.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="USTR2">USTR2()</a>
<br>Returns: <a href="design.html">Ustr string</a><br>Type: struct Ustr *
</td></tr><tr><td>Parameter<strong>[1]</strong>: Encoded 2nd byte of number of the length of <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: symbol
</td></tr><tr><td>Parameter<strong>[2]</strong>: Encoded 1st byte of number of the length of <a href="design.html">Ustr string</a><br>Type<strong>[2]</strong>: symbol
</td></tr><tr><td>Parameter<strong>[3]</strong>: Data for <a href="design.html">Ustr string</a><br>Type<strong>[3]</strong>: const char[]
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works in the same way as <a href="functions.html#USTR1">USTR1()</a> but takes two length bytes, so
 the read-only string can be upto 65,535 (2**16 - 1) bytes in length.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="USTR4">USTR4()</a>
<br>Returns: <a href="design.html">Ustr string</a><br>Type: struct Ustr *
</td></tr><tr><td>Parameter<strong>[1]</strong>: Encoded 4th byte of number of the length of <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: symbol
</td></tr><tr><td>Parameter<strong>[2]</strong>: Encoded 3rd byte of number of the length of <a href="design.html">Ustr string</a><br>Type<strong>[2]</strong>: symbol
</td></tr><tr><td>Parameter<strong>[3]</strong>: Encoded 2nd byte of number of the length of <a href="design.html">Ustr string</a><br>Type<strong>[3]</strong>: symbol
</td></tr><tr><td>Parameter<strong>[4]</strong>: Encoded 1st byte of number of the length of <a href="design.html">Ustr string</a><br>Type<strong>[4]</strong>: symbol
</td></tr><tr><td>Parameter<strong>[5]</strong>: Data for <a href="design.html">Ustr string</a><br>Type<strong>[5]</strong>: const char[]
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works in the same way as <a href="functions.html#USTR1">USTR1()</a> but takes four length bytes, so
 the read-only string can be upto 2**32 - 1 bytes in length.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="USTR1_CHK">USTR1_CHK()</a>
<br>Returns: <a href="design.html">Ustr string</a><br>Type: struct Ustr *
</td></tr><tr><td>Parameter<strong>[1]</strong>: Encoded number of the length of <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: symbol
</td></tr><tr><td>Parameter<strong>[2]</strong>: Data for <a href="design.html">Ustr string</a><br>Type<strong>[2]</strong>: const char[]
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works in the same way as <a href="functions.html#USTR1">USTR1()</a> but it does a check against
 the length of (Parameter[2]) using sizeof() - 1.

</td></tr><tr><td><strong>Note:</strong></td></tr><tr><td><p>
</p><p>  If the check fails the returned Ustr * will be &quot;&quot;, so you can check
 <a href="functions.html#ustr_len">ustr_len()</a> to see if you screwed something up.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="USTR2_CHK">USTR2_CHK()</a>
<br>Returns: <a href="design.html">Ustr string</a><br>Type: struct Ustr *
</td></tr><tr><td>Parameter<strong>[1]</strong>: Encoded 2nd byte of number of the length of <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: symbol
</td></tr><tr><td>Parameter<strong>[2]</strong>: Encoded 1st byte of number of the length of <a href="design.html">Ustr string</a><br>Type<strong>[2]</strong>: symbol
</td></tr><tr><td>Parameter<strong>[3]</strong>: Data for <a href="design.html">Ustr string</a><br>Type<strong>[3]</strong>: const char[]
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works in the same way as <a href="functions.html#USTR2">USTR2()</a> but it does a check against
 the length of (Parameter[2]) using sizeof() - 1.

</td></tr><tr><td><strong>Note:</strong></td></tr><tr><td><p>
</p><p>  If the check fails the returned Ustr * will be &quot;&quot;.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="USTR4_CHK">USTR4_CHK()</a>
<br>Returns: <a href="design.html">Ustr string</a><br>Type: struct Ustr *
</td></tr><tr><td>Parameter<strong>[1]</strong>: Encoded 4th byte of number of the length of <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: symbol
</td></tr><tr><td>Parameter<strong>[2]</strong>: Encoded 3rd byte of number of the length of <a href="design.html">Ustr string</a><br>Type<strong>[2]</strong>: symbol
</td></tr><tr><td>Parameter<strong>[3]</strong>: Encoded 2nd byte of number of the length of <a href="design.html">Ustr string</a><br>Type<strong>[3]</strong>: symbol
</td></tr><tr><td>Parameter<strong>[4]</strong>: Encoded 1st byte of number of the length of <a href="design.html">Ustr string</a><br>Type<strong>[4]</strong>: symbol
</td></tr><tr><td>Parameter<strong>[5]</strong>: Data for <a href="design.html">Ustr string</a><br>Type<strong>[5]</strong>: const char[]
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works in the same way as <a href="functions.html#USTR4">USTR4()</a> but it does a check against
 the length of (Parameter[2]) using sizeof() - 1.

</td></tr><tr><td><strong>Note:</strong></td></tr><tr><td><p>
</p><p>  If the check fails the returned Ustr * will be &quot;&quot;.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="USTRP1">USTRP1()</a>
<br>Returns: <a href="design.html">Ustr string</a><br>Type: struct Ustr *
</td></tr><tr><td>Parameter<strong>[1]</strong>: Encoded number of the length of <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: symbol
</td></tr><tr><td>Parameter<strong>[2]</strong>: Data for <a href="design.html">Ustr string</a><br>Type<strong>[2]</strong>: const char[]
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works like <a href="functions.html#USTR1">USTR1()</a>, but returns a Ustrp instead.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="USTRP2">USTRP2()</a>
<br>Returns: <a href="design.html">Ustr string</a><br>Type: struct Ustr *
</td></tr><tr><td>Parameter<strong>[1]</strong>: Encoded 2nd byte of number of the length of <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: symbol
</td></tr><tr><td>Parameter<strong>[2]</strong>: Encoded 1st byte of number of the length of <a href="design.html">Ustr string</a><br>Type<strong>[2]</strong>: symbol
</td></tr><tr><td>Parameter<strong>[3]</strong>: Data for <a href="design.html">Ustr string</a><br>Type<strong>[3]</strong>: const char[]
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works like <a href="functions.html#USTR4">USTR4()</a>, but returns a Ustrp instead.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="USTRP4">USTRP4()</a>
<br>Returns: <a href="design.html">Ustrp string</a><br>Type: struct Ustrp *
</td></tr><tr><td>Parameter<strong>[1]</strong>: Encoded 4th byte of number of the length of <a href="design.html">Ustrp string</a><br>Type<strong>[1]</strong>: symbol
</td></tr><tr><td>Parameter<strong>[2]</strong>: Encoded 3rd byte of number of the length of <a href="design.html">Ustrp string</a><br>Type<strong>[2]</strong>: symbol
</td></tr><tr><td>Parameter<strong>[3]</strong>: Encoded 2nd byte of number of the length of <a href="design.html">Ustrp string</a><br>Type<strong>[3]</strong>: symbol
</td></tr><tr><td>Parameter<strong>[4]</strong>: Encoded 1st byte of number of the length of <a href="design.html">Ustrp string</a><br>Type<strong>[4]</strong>: symbol
</td></tr><tr><td>Parameter<strong>[5]</strong>: Data for <a href="design.html">Ustr string</a><br>Type<strong>[5]</strong>: const char[]
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works like <a href="functions.html#USTR2">USTR2()</a>, but returns a Ustrp instead.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="USTRP1_CHK">USTRP1_CHK()</a>
<br>Returns: <a href="design.html">Ustr string</a><br>Type: struct Ustr *
</td></tr><tr><td>Parameter<strong>[1]</strong>: Encoded number of the length of <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: symbol
</td></tr><tr><td>Parameter<strong>[2]</strong>: Data for <a href="design.html">Ustr string</a><br>Type<strong>[2]</strong>: const char[]
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works like USTR1_CHK(), but returns a Ustrp instead.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="USTRP2_CHK">USTRP2_CHK()</a>
<br>Returns: <a href="design.html">Ustr string</a><br>Type: struct Ustr *
</td></tr><tr><td>Parameter<strong>[1]</strong>: Encoded 2nd byte of number of the length of <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: symbol
</td></tr><tr><td>Parameter<strong>[2]</strong>: Encoded 1st byte of number of the length of <a href="design.html">Ustr string</a><br>Type<strong>[2]</strong>: symbol
</td></tr><tr><td>Parameter<strong>[3]</strong>: Data for <a href="design.html">Ustr string</a><br>Type<strong>[3]</strong>: const char[]
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works like USTR4_CHK(), but returns a Ustrp instead.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="USTRP4_CHK">USTRP4_CHK()</a>
<br>Returns: <a href="design.html">Ustrp string</a><br>Type: struct Ustrp *
</td></tr><tr><td>Parameter<strong>[1]</strong>: Encoded 4th byte of number of the length of <a href="design.html">Ustrp string</a><br>Type<strong>[1]</strong>: symbol
</td></tr><tr><td>Parameter<strong>[2]</strong>: Encoded 3rd byte of number of the length of <a href="design.html">Ustrp string</a><br>Type<strong>[2]</strong>: symbol
</td></tr><tr><td>Parameter<strong>[3]</strong>: Encoded 2nd byte of number of the length of <a href="design.html">Ustrp string</a><br>Type<strong>[3]</strong>: symbol
</td></tr><tr><td>Parameter<strong>[4]</strong>: Encoded 1st byte of number of the length of <a href="design.html">Ustrp string</a><br>Type<strong>[4]</strong>: symbol
</td></tr><tr><td>Parameter<strong>[5]</strong>: Data for <a href="design.html">Ustr string</a><br>Type<strong>[5]</strong>: const char[]
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works like USTR2_CHK(), but returns a Ustrp instead.


</td></tr></table><table width="90%"><tr><td class="sect"><h2><a id="Creating%20fixed%20Ustr%20functions">Creating fixed Ustr functions</a></h2>
</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="USTR_SIZE_FIXED">USTR_SIZE_FIXED()</a>
<br>Returns: Size of area of memory<br>Type: size_t
</td></tr><tr><td>Parameter<strong>[1]</strong>: Size of area of memory<br>Type<strong>[1]</strong>: size_t
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This macro function is replaced by a static conversion from the max length
 desired (Parameter[1]) to the storage size needed. In other words it works out
 what <a href="functions.html#ustr_size_overhead">ustr_size_overhead()</a> will be, and adds that value.

</td></tr><tr><td><strong>Note:</strong></td></tr><tr><td><p>
</p><p>  This is useful is you want a small fixed size allocation, as you can declare
 it like so:

</p><p>  char buf[USTR_SIZE_FIXED(4)];

 ...to give you exactly 4 bytes as a maximum, this is esp. useful if you want
 a limited (<a href="functions.html#ustr_limited">ustr_limited()</a> == <a href="constants.html#USTR_TRUE">USTR_TRUE</a>) <a href="design.html">Ustr string</a>.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_init_fixed">ustr_init_fixed()</a>
<br>Returns: <a href="design.html">Ustr string</a><br>Type: struct Ustr *
</td></tr><tr><td>Parameter<strong>[1]</strong>: Pointer to area of memory to use as a <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: void *
</td></tr><tr><td>Parameter<strong>[2]</strong>: Size of area of memory<br>Type<strong>[2]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[3]</strong>: Whether the fixed size Ustr should be limited<br>Type<strong>[3]</strong>: int
</td></tr><tr><td>Parameter<strong>[4]</strong>: The initial length of the Ustr<br>Type<strong>[4]</strong>: size_t
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This creates a new <a href="design.html">Ustr string</a>, which is &quot;fixed&quot;. This means the Ustr storage
 is managed outside of the ustr_* API, it is often used for stack allocated
 strings.
</p><p>  As you add data to the Ustr past the size allowed via. the fixed storge the
 Ustr will automatically be converted into an allocated Ustr. So if this is
 possible you should always call <a href="functions.html#ustr_free">ustr_free()</a>, as this does nothing if given a
 fixed size Ustr.

</td></tr><tr><td><strong>Note:</strong></td></tr><tr><td><p>
</p><p>  For simplicity you probably want to use <a href="functions.html#USTR_SC_INIT_AUTO">USTR_SC_INIT_AUTO()</a> or
 <a href="functions.html#USTR_SC_INIT_AUTO">USTR_SC_INIT_AUTO()</a> when possible.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="USTR_SC_INIT_AUTO">USTR_SC_INIT_AUTO()</a>
<br>Returns: <a href="design.html">Ustr string</a><br>Type: struct Ustr *
</td></tr><tr><td>Parameter<strong>[1]</strong>: Area of memory to use as a <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: char[]
</td></tr><tr><td>Parameter<strong>[2]</strong>: Whether the fixed size Ustr should be limited<br>Type<strong>[2]</strong>: int
</td></tr><tr><td>Parameter<strong>[3]</strong>: The initial length of the Ustr<br>Type<strong>[3]</strong>: size_t
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This calls <a href="functions.html#ustr_init_fixed">ustr_init_fixed()</a> with sizeof() the area of memory (Parameter[1])
 as the second argument.

</td></tr><tr><td><strong>Note:</strong></td></tr><tr><td><p>
</p><p>  This does mean that the first argument must be the correct size, as far as
 sizeof() is concerned, as in...
</p><pre>
 char buf_sz[1024];
 Ustr *s1 = USTR_SC_INIT_AUTO(buf_sz, USTR_FALSE, 0);

</pre><p> ...so passing pointers to memory from malloc() will probably just return NULL.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="USTR_SC_INIT_AUTO_OSTR">USTR_SC_INIT_AUTO_OSTR()</a>
<br>Returns: <a href="design.html">Ustr string</a><br>Type: struct Ustr *
</td></tr><tr><td>Parameter<strong>[1]</strong>: Area of memory to use as a <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: char[]
</td></tr><tr><td>Parameter<strong>[2]</strong>: Whether the fixed size Ustr should be limited<br>Type<strong>[2]</strong>: int
</td></tr><tr><td>Parameter<strong>[3]</strong>: The initial string in the buffer, as a constant string<br>Type<strong>[3]</strong>: size_t
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This calls <a href="functions.html#ustr_init_fixed">ustr_init_fixed()</a> with sizeof() the area of memory (Parameter[1])
 as the second argument, given as an "object string".

</td></tr><tr><td><strong>Note:</strong></td></tr><tr><td><p>
</p><p>  This does mean that the first argument must be the correct size, as far as
 sizeof() is concerned, as in...
</p><pre>
 char buf_sz[1024] = USTR_BEG_FIXED2 "abcd";
 Ustr *s1 = USTR_SC_INIT_AUTO_OSTR(buf_sz, USTR_FALSE, "abcd");

</pre><p> ...so passing pointers to memory from malloc() will probably just return NULL.


</td></tr></table><table width="90%"><tr><td class="sect"><h2><a id="Debugging%20functions">Debugging functions</a></h2>
</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_assert_valid">ustr_assert_valid()</a>
<br>Returns: Success or failure<br>Type: int
</td></tr><tr><td>Parameter<strong>[1]</strong>: Pointer to a <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: Ustr *
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function asserts a few internal consistency checks, and can help point
 out when a Ustr is invalid.

</td></tr><tr><td><strong>Note:</strong></td></tr><tr><td><p>
</p><p>  This calls <a href="functions.html#ustr_assert_ret">ustr_assert_ret()</a> so that when <a href="constants.html#USTR_DEBUG">USTR_DEBUG</a> if off the checks are
 still performed and the result is returned.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_assert_valid_subustr">ustr_assert_valid_subustr()</a>
<br>Returns: Success or failure<br>Type: int
</td></tr><tr><td>Parameter<strong>[1]</strong>: Pointer to a <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: Ustr *
</td></tr><tr><td>Parameter<strong>[2]</strong>: Position in the Ustr<br>Type<strong>[2]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[3]</strong>: Length to delete from the Ustr<br>Type<strong>[3]</strong>:  size_t
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function calls <a href="functions.html#ustr_assert_valid">ustr_assert_valid()</a> and also checks that the position and
 length are within the Ustr. If they aren't valid it returns 0, if they are
 valid it returns <a href="functions.html#ustr_len">ustr_len()</a>.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="USTR_CNTL_MALLOC_CHECK_BEG">USTR_CNTL_MALLOC_CHECK_BEG()</a>
<br>Returns: Success or failure<br>Type: int
</td></tr><tr><td>Parameter<strong>[1]</strong>: Condition for begin malloc checking or not<br>Type<strong>[1]</strong>: int

</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function begins malloc checking, meaning all ustr allocations will go
 through the malloc check routines, but it fails if the condition
 check (Parameter[1]) fails.

</td></tr><tr><td><strong>Note:</strong></td></tr><tr><td><p>
</p><p>  Turning malloc checking on after one or more allocations has happened will
 lead to false failures unless you really known what you are doing.
</p><p>  You can automatically turn malloc checking on by giving the <a href="constants.html#USTR_CNTL_MC">USTR_CNTL_MC</a>
 environment variable the value of "1", "yes" or "on".


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="USTR_CNTL_MALLOC_CHECK_LVL">USTR_CNTL_MALLOC_CHECK_LVL()</a>
<br>Returns: Level of current malloc check<br>Type: int
</td></tr><tr><td>Parameter<strong>[1]</strong>: Nothing<br>Type<strong>[1]</strong>: void
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function returns the current &quot;level&quot; of the malloc check, with 0
 indicating that malloc check isn't enabled.
</p><p>  The level goes up by one whenever <a href="functions.html#USTR_CNTL_MALLOC_CHECK_BEG">USTR_CNTL_MALLOC_CHECK_BEG()</a> or
 <a href="functions.html#USTR_CNTL_MALLOC_CHECK_ADD">USTR_CNTL_MALLOC_CHECK_ADD()</a> returns success, and goes down by one whenever
 <a href="functions.html#USTR_CNTL_MALLOC_CHECK_DEL">USTR_CNTL_MALLOC_CHECK_DEL()</a> or <a href="functions.html#USTR_CNTL_MALLOC_CHECK_END">USTR_CNTL_MALLOC_CHECK_END()</a> returns success.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="USTR_CNTL_MALLOC_CHECK_MEM">USTR_CNTL_MALLOC_CHECK_MEM()</a>
<br>Returns: Success or failure<br>Type: int
</td></tr><tr><td>Parameter<strong>[1]</strong>: Pointer returned from malloc check<br>Type<strong>[1]</strong>: void *
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function asserts that the pointer (Parameter[1]) was allocated from
 malloc checking.

</td></tr><tr><td><strong>Note:</strong></td></tr><tr><td><p>
</p><p>  Unless you are doing something special, or using a builtin Ustr_pool it is
 very likely you want to just call <a href="functions.html#USTR_CNTL_MALLOC_CHECK_MEM_USTR">USTR_CNTL_MALLOC_CHECK_MEM_USTR()</a>.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="USTR_CNTL_MALLOC_CHECK_MEM_SZ">USTR_CNTL_MALLOC_CHECK_MEM_SZ()</a>
<br>Returns: Success or failure<br>Type: int
</td></tr><tr><td>Parameter<strong>[1]</strong>: Pointer returned from malloc check<br>Type<strong>[1]</strong>: void *
</td></tr><tr><td>Parameter<strong>[2]</strong>: Length of allocated memory<br>Type<strong>[2]</strong>: size_t
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function asserts that the pointer (Parameter[1]) was allocated from
 malloc checking, and has the specified size (Parameter[2]).

</td></tr><tr><td><strong>Note:</strong></td></tr><tr><td><p>
</p><p>  Unless you are doing something special, or using a builtin Ustr_pool it is
 very likely you want to just call <a href="functions.html#USTR_CNTL_MALLOC_CHECK_MEM_USTR">USTR_CNTL_MALLOC_CHECK_MEM_USTR()</a>.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="USTR_CNTL_MALLOC_CHECK_MEM_MINSZ">USTR_CNTL_MALLOC_CHECK_MEM_MINSZ()</a>
<br>Returns: Success or failure<br>Type: int
</td></tr><tr><td>Parameter<strong>[1]</strong>: Pointer returned from malloc check<br>Type<strong>[1]</strong>: void *
</td></tr><tr><td>Parameter<strong>[2]</strong>: Length of allocated memory<br>Type<strong>[2]</strong>: size_t
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function asserts that the pointer (Parameter[1]) was allocated from
 malloc checking, and has at least the specified size (Parameter[2]).

</td></tr><tr><td><strong>Note:</strong></td></tr><tr><td><p>
</p><p>  Unless you are doing something special, or using a builtin Ustr_pool it is
 very likely you want to just call <a href="functions.html#USTR_CNTL_MALLOC_CHECK_MEM_USTR">USTR_CNTL_MALLOC_CHECK_MEM_USTR()</a>.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="USTR_CNTL_MALLOC_CHECK_MEM_USTR">USTR_CNTL_MALLOC_CHECK_MEM_USTR()</a>
<br>Returns: Success or failure<br>Type: int
</td></tr><tr><td>Parameter<strong>[1]</strong>: Pointer to a <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: Ustr *
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function asserts that the pointer (Parameter[1]) is a Ustr allocated from
 malloc checking, if the Ustr is allocated (if not it returns TRUE).

</td></tr><tr><td><strong>Note:</strong></td></tr><tr><td><p>
</p><p>  Because of the layering between the Ustr code and the pool code, if you
 allocate an implicity sized Ustrp from a pool and then delete some data from
 it (which fails) the Ustr layer will think it has an implicit less than the
 actual size so this function will fail. This is what
 <a href="functions.html#USTR_CNTL_MALLOC_CHECK_MEM_USTRP">USTR_CNTL_MALLOC_CHECK_MEM_USTRP()</a> is for.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="USTR_CNTL_MALLOC_CHECK_MEM_USTRP">USTR_CNTL_MALLOC_CHECK_MEM_USTRP()</a>
<br>Returns: Success or failure<br>Type: int
</td></tr><tr><td>Parameter<strong>[1]</strong>: Pointer to a <a href="design.html">Ustrp string</a><br>Type<strong>[1]</strong>: Ustrp *
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function asserts that the pointer (Parameter[1]) is a Ustr allocated from
 a builtin pool using malloc checking, if the Ustr is allocated (if not it
 returns TRUE).


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="USTR_CNTL_MALLOC_CHECK_END">USTR_CNTL_MALLOC_CHECK_END()</a>
<br>Returns: Success or failure<br>Type: int
</td></tr><tr><td>Parameter<strong>[1]</strong>: Nothing<br>Type<strong>[1]</strong>: void
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This macro will cleanup any memory used by malloc check, and assert that
 no memory is left allocated.

</td></tr><tr><td><strong>Note:</strong></td></tr><tr><td><p>
</p><p>  If any memory is left allocated, each one found is output to stderr with
 the file/line/function of the level it was allocated from.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="USTR_CNTL_MALLOC_CHECK_ADD">USTR_CNTL_MALLOC_CHECK_ADD()</a>
<br>Returns: Success or failure<br>Type: int
</td></tr><tr><td>Parameter<strong>[1]</strong>: Condition to begin malloc checking or not<br>Type<strong>[1]</strong>: int
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works like <a href="functions.html#USTR_CNTL_MALLOC_CHECK_END">USTR_CNTL_MALLOC_CHECK_END()</a> but it fails if the
 condition check (Parameter[1]) fails, or if <a href="functions.html#USTR_CNTL_MALLOC_CHECK_LVL">USTR_CNTL_MALLOC_CHECK_LVL()</a> is
 zero.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="USTR_CNTL_MALLOC_CHECK_DEL">USTR_CNTL_MALLOC_CHECK_DEL()</a>
<br>Returns: Success or failure<br>Type: int
</td></tr><tr><td>Parameter<strong>[1]</strong>: Condition to end malloc checking or not<br>Type<strong>[1]</strong>: int
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works like <a href="functions.html#USTR_CNTL_MALLOC_CHECK_END">USTR_CNTL_MALLOC_CHECK_END()</a> but it fails if the
 condition check (Parameter[1]) fails, or if <a href="functions.html#USTR_CNTL_MALLOC_CHECK_LVL">USTR_CNTL_MALLOC_CHECK_LVL()</a> is
 one.

</td></tr><tr><td><strong>Note:</strong></td></tr><tr><td><p>
</p><p>  The condition (Parameter[1]) to this macro should almost certainly be the
 return value from <a href="functions.html#USTR_CNTL_MALLOC_CHECK_ADD">USTR_CNTL_MALLOC_CHECK_ADD()</a>.


</td></tr></table><table width="90%"><tr><td class="sect"><h2><a id="Creating%20allocated%20Ustr%20functions">Creating allocated Ustr functions</a></h2>
</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_init_size">ustr_init_size()</a>
<br>Returns: Size that needs to be allocated<br>Type: size_t 
</td></tr><tr><td>Parameter<strong>[1]</strong>: Size of allocated storage<br>Type<strong>[1]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[2]</strong>: Number of bytes to use for reference count<br>Type<strong>[2]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[3]</strong>: Exact memory allocations<br>Type<strong>[3]</strong>: int
</td></tr><tr><td>Parameter<strong>[4]</strong>: Length of data in the Ustr<br>Type<strong>[4]</strong>: size_t
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function finds out the exact size of memory needed to store the
 specified Ustr of the given configuration.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_init_alloc">ustr_init_alloc()</a>
<br>Returns: <a href="design.html">Ustr string</a><br>Type: struct Ustr *
</td></tr><tr><td>Parameter<strong>[1]</strong>: Pointer to area of memory to use as a <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: void *
</td></tr><tr><td>Parameter<strong>[2]</strong>: Size of area of memory<br>Type<strong>[2]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[3]</strong>: Whether Ustr should store the size<br>Type<strong>[3]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[4]</strong>: Number of bytes to use for references<br>Type<strong>[4]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[5]</strong>: Whether the Ustr should use exact allocations<br>Type<strong>[5]</strong>: int
</td></tr><tr><td>Parameter<strong>[6]</strong>: Whether the Ustr should have the &quot;enomem&quot; flag set<br>Type<strong>[6]</strong>: int
</td></tr><tr><td>Parameter<strong>[7]</strong>: The initial length of the Ustr<br>Type<strong>[7]</strong>: size_t
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This creates a new <a href="design.html">Ustr string</a>, you should have allocated the data via. 
 <a href="functions.html#USTR_CONF_MALLOC">USTR_CONF_MALLOC()</a> or bad things will happen if the <a href="design.html">Ustr string</a> is ever free'd
 or reallocated.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_dupx_empty">ustr_dupx_empty()</a>
<br>Returns: <a href="design.html">Ustr string</a><br>Type: struct Ustr *
</td></tr><tr><td>Parameter<strong>[1]</strong>: Size of allocated storage<br>Type<strong>[1]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[2]</strong>: Number of bytes to use for reference count<br>Type<strong>[2]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[3]</strong>: Exact memory allocation flag<br>Type<strong>[3]</strong>: int
</td></tr><tr><td>Parameter<strong>[4]</strong>: ENOMEM, memory error flag<br>Type<strong>[4]</strong>: int
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function creates an empty Ustr, owned by you, that is allocated
 from system memory, or it returns NULL.
</p><p>  The size is the desired allocation size for the entire Ustr, including
 overhead for metadata. This value will be rounded up, if it's too small, so
 passing 1 as the size means you want a stored size but to allocate the smallest
 amount of memory possible.
</p><p>  The exact memory allocation flag says if the Ustr should round allocations up
 to the nearest half power of two or should be no more than needed.
</p><p>  The ENOMEM memory error flag sets the iniital state of the user visible flag
 for memory allocation errors. Eg. <a href="functions.html#ustr_enomem">ustr_enomem()</a>, <a href="functions.html#ustr_setf_enomem_clr">ustr_setf_enomem_clr()</a> and
 <a href="functions.html#ustr_setf_enomem_err">ustr_setf_enomem_err()</a>

</td></tr><tr><td><strong>Note:</strong></td></tr><tr><td><p>
</p><p>  The reference byte count can only be one of the following values: 0, 1, 2 or
 4, or 8 (on environments with a 64bit size_t).
</p><p>  It can be useful to ensure that the Ustr is in system memory, so that you can
 add things to it and check for errors with <a href="functions.html#ustr_enomem">ustr_enomem()</a>.
</p><p>  If you chose to store the allocated size in the Ustr then the number of bytes
 allocated for the reference count will be a minimum of 2.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_dup_empty">ustr_dup_empty()</a>
<br>Returns: <a href="design.html">Ustr string</a><br>Type: struct Ustr *
</td></tr><tr><td>Parameter<strong>[1]</strong>: Nothing<br>Type<strong>[1]</strong>: void
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function is the same as calling <a href="functions.html#ustr_dupx_empty">ustr_dupx_empty()</a> with the current set
 of default options.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_dupx_undef">ustr_dupx_undef()</a>
<br>Returns: <a href="design.html">Ustr string</a><br>Type: struct Ustr *
</td></tr><tr><td>Parameter<strong>[1]</strong>: Size of allocated storage<br>Type<strong>[1]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[2]</strong>: Number of bytes to use for reference count<br>Type<strong>[2]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[3]</strong>: Exact memory allocations<br>Type<strong>[3]</strong>: int
</td></tr><tr><td>Parameter<strong>[4]</strong>: ENOMEM, memory error flag<br>Type<strong>[4]</strong>: int
</td></tr><tr><td>Parameter<strong>[5]</strong>: Length of new undefined data<br>Type<strong>[5]</strong>: size_t
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works like you called <a href="functions.html#ustr_dupx_empty">ustr_dupx_empty()</a> and then
 <a href="functions.html#ustr_add_undef">ustr_add_undef()</a>.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_dup_undef">ustr_dup_undef()</a>
<br>Returns: Pointer to a <a href="design.html">Ustr string</a><br>Type: struct Ustr *
</td></tr><tr><td>Parameter<strong>[1]</strong>: Length of new undefined data<br>Type<strong>[1]</strong>: size_t
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function is the same as calling <a href="functions.html#ustr_dupx_undef">ustr_dupx_undef()</a> with the current set
 of default options.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_dup">ustr_dup()</a>
<br>Returns: A pointer to a <a href="design.html">Ustr string</a><br>Type: struct Ustr *
</td></tr><tr><td>Parameter<strong>[1]</strong>: Pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: const struct Ustr *
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function tries to increase the reference count on the passed <a href="design.html">Ustr string</a>,
 and if that succeeds returns that as an argument. If that fails it tries
 creates a new <a href="design.html">Ustr string</a> that looks identical to the old <a href="design.html">Ustr string</a>, apart
 from the reference count.

</td></tr><tr><td><strong>Note:</strong></td></tr><tr><td><p>
</p><p>  Because the new <a href="design.html">Ustr string</a> is configured identically to the old <a href="design.html">Ustr string</a>
 this means the result can be very different to what you get if you call
 <a href="functions.html#ustr_dup_buf">ustr_dup_buf()</a> with <a href="functions.html#ustr_cstr">ustr_cstr()</a> and <a href="functions.html#ustr_len">ustr_len()</a> from the original string where
 the configuration would be whatever the default is.
</p><p>  Esp. worth of note is that if you <a href="functions.html#ustr_dup">ustr_dup()</a> a <a href="design.html">Ustr string</a> with an explicit
 size of 900 but a length of 1, and the reference count is full the returned
 <a href="design.html">Ustr string</a> will have a size of 900 bytes and so will have allocated a little
 over that. <a href="functions.html#ustr_dup_buf">ustr_dup_buf()</a>, even with a sized configuration would only allocate
 about 12 bytes and have a size a little less than that.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_dupx">ustr_dupx()</a>
<br>Returns: Pointer to a <a href="design.html">Ustr string</a><br>Type: struct Ustr *
</td></tr><tr><td>Parameter<strong>[1]</strong>: Size of allocated storage<br>Type<strong>[1]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[2]</strong>: Number of bytes to use for reference count<br>Type<strong>[2]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[3]</strong>: Exact memory allocations<br>Type<strong>[3]</strong>: int
</td></tr><tr><td>Parameter<strong>[4]</strong>: ENOMEM, memory error flag<br>Type<strong>[4]</strong>: int
</td></tr><tr><td>Parameter<strong>[5]</strong>: Pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[5]</strong>: const struct Ustr *
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function tries to add a reference if the value of the size, reference
 bytes, exact memory allocations and ENOMEM are the same as those in the passed
 <a href="design.html">Ustr string</a> (Parameter[5]). If the comparison fails or the addition of a
 reference fails it works like <a href="functions.html#ustr_dupx_buf">ustr_dupx_buf()</a> using <a href="functions.html#ustr_cstr">ustr_cstr()</a> and <a href="functions.html#ustr_len">ustr_len()</a>.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_sc_dup">ustr_sc_dup()</a>
<br>Returns: A pointer to a <a href="design.html">Ustr string</a><br>Type: struct Ustr *
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a pointer to a <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: struct Ustr **
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works like calling <a href="functions.html#ustr_dup">ustr_dup()</a>, but if the reference count is
 maxed out then and so a new <a href="design.html">Ustr string</a> has been allocated then that is stored
 in the passed argument (Parameter[1]) and the "old" <a href="design.html">Ustr string</a> is returned.

</td></tr><tr><td><strong>Note:</strong></td></tr><tr><td><p>
</p><p>  The reason to use this is that if you have a &quot;main&quot; <a href="design.html">Ustr string</a> pointer that
 a lot of things are getting references too then when the reference count maxes
 out you'll degrade into worst case behaviour which acts as though there are no
 reference counts. This function stops that problem.
</p><p>  As an example, if you have a 1 byte reference count and have 255 * 2
 references then using <a href="functions.html#ustr_dup">ustr_dup()</a> will create 256 Ustr strings using this
 function will create 4 Ustr strings.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_sc_dupx">ustr_sc_dupx()</a>
<br>Returns: Pointer to a <a href="design.html">Ustr string</a><br>Type: struct Ustr *
</td></tr><tr><td>Parameter<strong>[1]</strong>: Size of allocated storage<br>Type<strong>[1]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[2]</strong>: Number of bytes to use for reference count<br>Type<strong>[2]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[3]</strong>: Exact memory allocations<br>Type<strong>[3]</strong>: int
</td></tr><tr><td>Parameter<strong>[4]</strong>: ENOMEM, memory error flag<br>Type<strong>[4]</strong>: int
</td></tr><tr><td>Parameter<strong>[5]</strong>: A pointer to a pointer to a <a href="design.html">Ustr string</a><br>Type<strong>[5]</strong>: struct Ustr **
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works like calling <a href="functions.html#ustr_dupx">ustr_dupx()</a>, but if the reference count is
 maxed out then and so a new <a href="design.html">Ustr string</a> is allocated then that is stored in
 the passed argument (Parameter[1]) and the "old" <a href="design.html">Ustr string</a> is returned.
</p><p>  If the configurations of the new <a href="design.html">Ustr string</a> and the old <a href="design.html">Ustr string</a> are not
 the same, this function works identically to <a href="functions.html#ustr_dupx">ustr_dupx()</a>.

</td></tr><tr><td><strong>Note:</strong></td></tr><tr><td><p>
</p><p>  The reason to use this is that if you have a &quot;main&quot; <a href="design.html">Ustr string</a> pointer that
 a lot of things are getting references too then when the reference count maxes
 out you'll degrade into worst case behaviour which acts as though there are no
 reference counts. This function stops that problem.
</p><p>  As an example, if you have a 1 byte reference count and have 255 * 2
 references then using <a href="functions.html#ustr_dupx">ustr_dupx()</a> will create 256 Ustr strings using this
 function will create 4 Ustr strings.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_dup_buf">ustr_dup_buf()</a>
<br>Returns: A pointer to a <a href="design.html">Ustr string</a><br>Type: struct Ustr *
</td></tr><tr><td>Parameter<strong>[1]</strong>: Pointer to data<br>Type<strong>[1]</strong>: const void *
</td></tr><tr><td>Parameter<strong>[2]</strong>: Length of data<br>Type<strong>[2]</strong>: size_t
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works as if you had called <a href="functions.html#ustr_dup_undef">ustr_dup_undef()</a> and then copied the
 data into the new undefined space.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_dupx_buf">ustr_dupx_buf()</a>
<br>Returns: Pointer to a <a href="design.html">Ustr string</a><br>Type: struct Ustr *
</td></tr><tr><td>Parameter<strong>[1]</strong>: Size of allocated storage<br>Type<strong>[1]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[2]</strong>: Number of bytes to use for reference count<br>Type<strong>[2]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[3]</strong>: Exact memory allocations<br>Type<strong>[3]</strong>: int
</td></tr><tr><td>Parameter<strong>[4]</strong>: ENOMEM, memory error flag<br>Type<strong>[4]</strong>: int
</td></tr><tr><td>Parameter<strong>[5]</strong>: Pointer to data<br>Type<strong>[5]</strong>: const void *
</td></tr><tr><td>Parameter<strong>[6]</strong>: Length of data<br>Type<strong>[6]</strong>: size_t
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works as if you had called <a href="functions.html#ustr_dupx_undef">ustr_dupx_undef()</a> and then copied the
 data into the new undefined space.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_dup_cstr">ustr_dup_cstr()</a>
<br>Returns: A pointer to a <a href="design.html">Ustr string</a><br>Type: struct Ustr *
</td></tr><tr><td>Parameter<strong>[1]</strong>: Pointer to constant C-style string<br>Type<strong>[1]</strong>: const char *
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works as if you had called <a href="functions.html#ustr_dup_buf">ustr_dup_buf()</a> and passed strlen() as
 the length.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_dupx_cstr">ustr_dupx_cstr()</a>
<br>Returns: Pointer to a <a href="design.html">Ustr string</a><br>Type: struct Ustr *
</td></tr><tr><td>Parameter<strong>[1]</strong>: Size of allocated storage<br>Type<strong>[1]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[2]</strong>: Number of bytes to use for reference count<br>Type<strong>[2]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[3]</strong>: Exact memory allocations<br>Type<strong>[3]</strong>: int
</td></tr><tr><td>Parameter<strong>[4]</strong>: ENOMEM, memory error flag<br>Type<strong>[4]</strong>: int
</td></tr><tr><td>Parameter<strong>[5]</strong>: Pointer to constant C-style string<br>Type<strong>[5]</strong>: const char *
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works as if you had called <a href="functions.html#ustr_dupx_buf">ustr_dupx_buf()</a> and passed strlen()
 as the length.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="USTR_DUP_OSTR">USTR_DUP_OSTR()</a>
<br>Returns: A pointer to a <a href="design.html">Ustr string</a><br>Type: struct Ustr *
</td></tr><tr><td>Parameter<strong>[1]</strong>: A constant C-style string<br>Type<strong>[1]</strong>: const char []
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works as if you had called <a href="functions.html#ustr_dup_buf">ustr_dup_buf()</a> and passed
 sizeof() - 1 as the length.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="USTR_DUP_OBJ">USTR_DUP_OBJ()</a>
<br>Returns: A pointer to a <a href="design.html">Ustr string</a><br>Type: struct Ustr *
</td></tr><tr><td>Parameter<strong>[1]</strong>: A symbol<br>Type<strong>[1]</strong>: ...
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works as if you had called <a href="functions.html#ustr_dup_buf">ustr_dup_buf()</a> and passed
 sizeof() as the length.

</td></tr><tr><td><strong>Note:</strong></td></tr><tr><td><p>
</p><p>  In most cases you'll want to use <a href="functions.html#USTR_DUP_OSTR">USTR_DUP_OSTR()</a>.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_dup_subustr">ustr_dup_subustr()</a>
<br>Returns: A pointer to a <a href="design.html">Ustr string</a><br>Type: struct Ustr *
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[2]</strong>: Position in the Ustr<br>Type<strong>[2]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[3]</strong>: Length to add from the Ustr<br>Type<strong>[3]</strong>: size_t
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function mostly works as if you had called <a href="functions.html#ustr_dup_buf">ustr_dup_buf()</a> with the
 <a href="functions.html#ustr_cstr">ustr_cstr()</a> + position - 1 and length values of the <a href="design.html">Ustr string</a> to be added.

</td></tr><tr><td><strong>Note:</strong></td></tr><tr><td><p>
</p><p>  If the position is 1 and the length is the length of the <a href="design.html">Ustr string</a> then it
 just calls <a href="functions.html#ustr_dup">ustr_dup()</a>.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_dupx_subustr">ustr_dupx_subustr()</a>
<br>Returns: Pointer to a <a href="design.html">Ustr string</a><br>Type: struct Ustr *
</td></tr><tr><td>Parameter<strong>[1]</strong>: Size of allocated storage<br>Type<strong>[1]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[2]</strong>: Number of bytes to use for reference count<br>Type<strong>[2]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[3]</strong>: Exact memory allocations<br>Type<strong>[3]</strong>: int
</td></tr><tr><td>Parameter<strong>[4]</strong>: ENOMEM, memory error flag<br>Type<strong>[4]</strong>: int
</td></tr><tr><td>Parameter<strong>[5]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[5]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[6]</strong>: Position in the Ustr<br>Type<strong>[6]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[7]</strong>: Length to add from the Ustr<br>Type<strong>[7]</strong>: size_t
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function mostly works as if you had called <a href="functions.html#ustr_dupx_buf">ustr_dupx_buf()</a> with the
 <a href="functions.html#ustr_cstr">ustr_cstr()</a> + position - 1 and length values of the <a href="design.html">Ustr string</a> to be added.

</td></tr><tr><td><strong>Note:</strong></td></tr><tr><td><p>
</p><p>  If the position is 1 and the length is the length of the <a href="design.html">Ustr string</a> then it
 just calls <a href="functions.html#ustr_dupx">ustr_dupx()</a>.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_dup_rep_chr">ustr_dup_rep_chr()</a>
<br>Returns: A pointer to a <a href="design.html">Ustr string</a><br>Type: struct Ustr *
</td></tr><tr><td>Parameter<strong>[1]</strong>: Byte value of data<br>Type<strong>[1]</strong>: char
</td></tr><tr><td>Parameter<strong>[2]</strong>: Length of bytes as data<br>Type<strong>[2]</strong>: size_t
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works as if you had called <a href="functions.html#ustr_dup_undef">ustr_dup_undef()</a> and then copied the
 byte value to each position.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_dupx_rep_chr">ustr_dupx_rep_chr()</a>
<br>Returns: Pointer to a <a href="design.html">Ustr string</a><br>Type: struct Ustr *
</td></tr><tr><td>Parameter<strong>[1]</strong>: Size of allocated storage<br>Type<strong>[1]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[2]</strong>: Number of bytes to use for reference count<br>Type<strong>[2]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[3]</strong>: Exact memory allocations<br>Type<strong>[3]</strong>: int
</td></tr><tr><td>Parameter<strong>[4]</strong>: ENOMEM, memory error flag<br>Type<strong>[4]</strong>: int
</td></tr><tr><td>Parameter<strong>[5]</strong>: Byte value of data<br>Type<strong>[5]</strong>: char
</td></tr><tr><td>Parameter<strong>[6]</strong>: Length of bytes as data<br>Type<strong>[6]</strong>: size_t
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works as if you had called <a href="functions.html#ustr_dupx_undef">ustr_dupx_undef()</a> and then copied the
 byte value to each position.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_sc_vjoin">ustr_sc_vjoin()</a>
<br>Returns: Pointer to a <a href="design.html">Ustr string</a><br>Type: struct Ustr *
</td></tr><tr><td>Parameter<strong>[1]</strong>: Separator to go between Ustr strings<br>Type<strong>[1]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[2]</strong>: A pointer to the first constant <a href="design.html">Ustr string</a><br>Type<strong>[2]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[3]</strong>: A pointer to the second constant <a href="design.html">Ustr string</a><br>Type<strong>[3]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[4]</strong>: Variable argument list variable, from va_start()<br>Type<strong>[4]</strong>: va_list
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works as if you called <a href="functions.html#ustr_dup">ustr_dup()</a> on the first Ustr
 string (Parameter[2]), and then <a href="functions.html#ustr_add">ustr_add()</a> on the separator (Parameter[1])
 followed by <a href="functions.html#ustr_add">ustr_add()</a> on the second <a href="design.html">Ustr string</a> (Parameter[3]). This process
 then repeats for all the Ustr strings in the variable argument list
 (Parameter[4]) until a <a href="constants.html#USTR_NULL">USTR_NULL</a> is reached.

</td></tr><tr><td><strong>Note:</strong></td></tr><tr><td><p>
</p><p>  This function doesn't guarantee to just take a reference to one of the passed
 Ustr strings, even if that is what would happen if you called the above
 manually.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_sc_join">ustr_sc_join()</a>
<br>Returns: Pointer to a <a href="design.html">Ustr string</a><br>Type: struct Ustr *
</td></tr><tr><td>Parameter<strong>[1]</strong>: Separator to go between Ustr strings<br>Type<strong>[1]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[2]</strong>: A pointer to the first constant <a href="design.html">Ustr string</a><br>Type<strong>[2]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[3]</strong>: A pointer to the second constant <a href="design.html">Ustr string</a><br>Type<strong>[3]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[4]</strong>: Zero or more pointers to constant Ustr strings and then USTR_NULL<br>Type<strong>[4]</strong>: ...
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function calls va_start() to get a variable argument list and then calls
 <a href="functions.html#ustr_sc_vjoin">ustr_sc_vjoin()</a>.

</td></tr><tr><td><strong>Note:</strong></td></tr><tr><td><p>
</p><p>  This function doesn't guarantee to just take a reference to one of the passed
 Ustr strings, even if that is what would happen if you called the above
 manually.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_sc_vjoinx">ustr_sc_vjoinx()</a>
<br>Returns: Pointer to a <a href="design.html">Ustr string</a><br>Type: struct Ustr *
</td></tr><tr><td>Parameter<strong>[1]</strong>: Size of allocated storage<br>Type<strong>[1]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[2]</strong>: Number of bytes to use for reference count<br>Type<strong>[2]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[3]</strong>: Exact memory allocations<br>Type<strong>[3]</strong>: int
</td></tr><tr><td>Parameter<strong>[4]</strong>: ENOMEM, memory error flag<br>Type<strong>[4]</strong>: int
</td></tr><tr><td>Parameter<strong>[5]</strong>: Separator to go between Ustr strings<br>Type<strong>[5]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[6]</strong>: A pointer to the first constant <a href="design.html">Ustr string</a><br>Type<strong>[6]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[7]</strong>: A pointer to the second constant <a href="design.html">Ustr string</a><br>Type<strong>[7]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[8]</strong>: Variable argument list variable, from va_start()<br>Type<strong>[8]</strong>: va_list
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works as if you called <a href="functions.html#ustr_dupx">ustr_dupx()</a> on the first Ustr
 string (Parameter[2]), and then <a href="functions.html#ustr_add">ustr_add()</a> on the separator (Parameter[1])
 followed by <a href="functions.html#ustr_add">ustr_add()</a> on the second <a href="design.html">Ustr string</a> (Parameter[3]). This process
 then repeats for all the Ustr strings in the variable argument list
 (Parameter[4]) until a <a href="constants.html#USTR_NULL">USTR_NULL</a> is reached.

</td></tr><tr><td><strong>Note:</strong></td></tr><tr><td><p>
</p><p>  This function doesn't guarantee to just take a reference to one of the passed
 Ustr strings, even if that is what would happen if you called the above
 manually.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_sc_joinx">ustr_sc_joinx()</a>
<br>Returns: Pointer to a <a href="design.html">Ustr string</a><br>Type: struct Ustr *
</td></tr><tr><td>Parameter<strong>[1]</strong>: Size of allocated storage<br>Type<strong>[1]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[2]</strong>: Number of bytes to use for reference count<br>Type<strong>[2]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[3]</strong>: Exact memory allocations<br>Type<strong>[3]</strong>: int
</td></tr><tr><td>Parameter<strong>[4]</strong>: ENOMEM, memory error flag<br>Type<strong>[4]</strong>: int
</td></tr><tr><td>Parameter<strong>[5]</strong>: Separator to go between Ustr strings<br>Type<strong>[5]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[6]</strong>: A pointer to the first constant <a href="design.html">Ustr string</a><br>Type<strong>[6]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[7]</strong>: A pointer to the second constant <a href="design.html">Ustr string</a><br>Type<strong>[7]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[8]</strong>: Zero or more pointers to constant Ustr strings and then USTR_NULL<br>Type<strong>[8]</strong>: ...
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function calls va_start() to get a variable argument list and then calls
 <a href="functions.html#ustr_sc_vjoinx">ustr_sc_vjoinx()</a>.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_sc_vconcat">ustr_sc_vconcat()</a>
<br>Returns: Pointer to a <a href="design.html">Ustr string</a><br>Type: struct Ustr *
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to the first constant <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[2]</strong>: Variable argument list variable, from va_start()<br>Type<strong>[2]</strong>: va_list
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works as if you called <a href="functions.html#ustr_dup">ustr_dup()</a> on the first Ustr
 string (Parameter[1]), and then <a href="functions.html#ustr_add">ustr_add()</a> on the second Ustr
 string (Parameter[3]). This process then repeats for all the Ustr strings in
 the variable argument list (Parameter[4]) until a <a href="constants.html#USTR_NULL">USTR_NULL</a> is reached.

</td></tr><tr><td><strong>Note:</strong></td></tr><tr><td><p>
</p><p>  This function doesn't guarantee to just take a reference to one of the passed
 Ustr strings, even if that is what would happen if you called the above
 manually.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_sc_concat">ustr_sc_concat()</a>
<br>Returns: Pointer to a <a href="design.html">Ustr string</a><br>Type: struct Ustr *
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to the first constant <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[2]</strong>: Zero or more pointers to constant Ustr strings and then USTR_NULL<br>Type<strong>[2]</strong>: ...
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function calls va_start() to get a variable argument list and then calls
 <a href="functions.html#ustr_sc_vconcat">ustr_sc_vconcat()</a>.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_sc_vconcatx">ustr_sc_vconcatx()</a>
<br>Returns: Pointer to a <a href="design.html">Ustr string</a><br>Type: struct Ustr *
</td></tr><tr><td>Parameter<strong>[1]</strong>: Size of allocated storage<br>Type<strong>[1]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[2]</strong>: Number of bytes to use for reference count<br>Type<strong>[2]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[3]</strong>: Exact memory allocations<br>Type<strong>[3]</strong>: int
</td></tr><tr><td>Parameter<strong>[4]</strong>: ENOMEM, memory error flag<br>Type<strong>[4]</strong>: int
</td></tr><tr><td>Parameter<strong>[5]</strong>: A pointer to the first constant <a href="design.html">Ustr string</a><br>Type<strong>[5]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[6]</strong>: Variable argument list variable, from va_start()<br>Type<strong>[6]</strong>: va_list
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works as if you called <a href="functions.html#ustr_dupx">ustr_dupx()</a> on the first Ustr
 string (Parameter[1]), and then <a href="functions.html#ustr_add">ustr_add()</a> on the second Ustr
 string (Parameter[3]). This process then repeats for all the Ustr strings in
 the variable argument list (Parameter[4]) until a <a href="constants.html#USTR_NULL">USTR_NULL</a> is reached.

</td></tr><tr><td><strong>Note:</strong></td></tr><tr><td><p>
</p><p>  This function doesn't guarantee to just take a reference to one of the passed
 Ustr strings, even if that is what would happen if you called the above
 manually.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_sc_concatx">ustr_sc_concatx()</a>
<br>Returns: Pointer to a <a href="design.html">Ustr string</a><br>Type: struct Ustr *
</td></tr><tr><td>Parameter<strong>[1]</strong>: Size of allocated storage<br>Type<strong>[1]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[2]</strong>: Number of bytes to use for reference count<br>Type<strong>[2]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[3]</strong>: Exact memory allocations<br>Type<strong>[3]</strong>: int
</td></tr><tr><td>Parameter<strong>[4]</strong>: ENOMEM, memory error flag<br>Type<strong>[4]</strong>: int
</td></tr><tr><td>Parameter<strong>[5]</strong>: A pointer to the first constant <a href="design.html">Ustr string</a><br>Type<strong>[5]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[6]</strong>: Zero or more pointers to constant Ustr strings and then USTR_NULL<br>Type<strong>[6]</strong>: ...
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function calls va_start() to get a variable argument list and then calls
 <a href="functions.html#ustr_sc_vconcatx">ustr_sc_vconcatx()</a>.


</td></tr></table><table width="90%"><tr><td class="sect"><h2><a id="Deleting%20a%20Ustr%2c%20or%20data%20within%20a%20Ustr">Deleting a Ustr, or data within a Ustr</a></h2>
</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_free">ustr_free()</a>
<br>Returns: Nothing<br>Type: void 
</td></tr><tr><td>Parameter<strong>[1]</strong>: Pointer to a Ustr<br>Type<strong>[1]</strong>: struct Ustr *
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function decrements the reference count on a Ustr, if there is one, and
 free's it if it is allocated and the reference count becomes zero.

</td></tr><tr><td><strong>Note:</strong></td></tr><tr><td><p>
</p><p>  This function does nothing if passed <a href="constants.html#USTR_NULL">USTR_NULL</a>.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustrp_free">ustrp_free()</a>
<br>Returns: Nothing<br>Type: void 
</td></tr><tr><td>Parameter<strong>[1]</strong>: Pointer to a <a href="design.html#possibilities">Ustr pool</a> object<br>Type<strong>[1]</strong>: struct Ustr_pool *
</td></tr><tr><td>Parameter<strong>[2]</strong>: Pointer to a Ustrp (pool allocated Ustr)<br>Type<strong>[2]</strong>: struct Ustrp *
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works like <a href="functions.html#ustr_free">ustr_free()</a> but calls the pool_free member function
 of the Ustr_pool (Parameter[1]) instead of the ustr system free.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_sc_free">ustr_sc_free()</a>
<br>Returns: Nothing<br>Type: void 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a pointer to a <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: struct Ustr **
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function calls <a href="functions.html#ustr_free">ustr_free()</a> and then sets the pointer (Parameter[1]) to
 <a href="constants.html#USTR_NULL">USTR_NULL</a>, which is a noop when passed to <a href="functions.html#ustr_free">ustr_free()</a>. This can be used to
 help prevent "double free" errors.

</td></tr><tr><td><strong>Note:</strong></td></tr><tr><td><p>
</p><p>  While the point to the pointer must be non-NULL, this function also accepts
 a NULL ustr and does nothing. So you can pass the same pointer to this function
 multiple times and only the first one will do anything.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_sc_free2">ustr_sc_free2()</a>
<br>Returns: Nothing<br>Type: void 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a pointer to a <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: struct Ustr **
</td></tr><tr><td>Parameter<strong>[2]</strong>: Pointer to a <a href="design.html">Ustr string</a><br>Type<strong>[2]</strong>: struct Ustr *
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works like <a href="functions.html#ustr_sc_free">ustr_sc_free()</a> but instead of setting the
 pointer (Parameter[1]) to <a href="constants.html#USTR_NULL">USTR_NULL</a> it sets it to the Ustr
 string (Parameter[2]).

</td></tr><tr><td><strong>Note:</strong></td></tr><tr><td><p>
</p><p>  While the point to the pointer must be non-NULL, this function also accepts
 a NULL ustr to be free'd and does nothing. So you can pass the same pointer to
 <a href="functions.html#ustr_sc_free">ustr_sc_free()</a> and then this function safely.
</p><p>  The passed value (Parameter[2]) shouldn't be <a href="constants.html#USTR_NULL">USTR_NULL</a>, and in debugging mode
 the function will assert() that it isn't.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_sc_free_shared">ustr_sc_free_shared()</a>
<br>Returns: Nothing<br>Type: void 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a pointer to a <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: struct Ustr **
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function is a simple way to &quot;free&quot; a <a href="design.html">Ustr string</a> that has been
 shared (<a href="functions.html#ustr_shared">ustr_shared()</a> returns <a href="constants.html#USTR_TRUE">USTR_TRUE</a>), normally <a href="functions.html#ustr_free">ustr_free()</a> is ignored on a
 shared <a href="design.html">Ustr string</a>. It just calls <a href="functions.html#ustr_setf_owner">ustr_setf_owner()</a> and then <a href="functions.html#ustr_sc_free">ustr_sc_free()</a>.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_del">ustr_del()</a>
<br>Returns: Success or failure<br>Type: int 
</td></tr><tr><td>Parameter<strong>[1]</strong>: Pointer to a pointer to a <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: struct Ustr **
</td></tr><tr><td>Parameter<strong>[2]</strong>: Length to delete from the Ustr<br>Type<strong>[2]</strong>: size_t
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function deletes data from the end of Ustr, possibly re-sizing the Ustr
 at the same time.

</td></tr><tr><td><strong>Note:</strong></td></tr><tr><td><p>
</p><p>  The Ustr is never re-sized when the size is stored explicitly, so the pointer
 never changes.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_del_subustr">ustr_del_subustr()</a>
<br>Returns: Success or failure<br>Type: int 
</td></tr><tr><td>Parameter<strong>[1]</strong>: Pointer to a pointer to a <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: struct Ustr **
</td></tr><tr><td>Parameter<strong>[2]</strong>: Position in the Ustr<br>Type<strong>[2]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[3]</strong>: Length to delete from the Ustr<br>Type<strong>[3]</strong>:  size_t
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works like <a href="functions.html#ustr_del">ustr_del()</a> but can delete an arbitrary section of the
 Ustr.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_sc_del">ustr_sc_del()</a>
<br>Returns: Nothing<br>Type: void 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a pointer to a <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: struct Ustr **
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function is like calling <a href="functions.html#ustr_del">ustr_del()</a> with <a href="functions.html#ustr_len">ustr_len()</a> as the length,
 however if that fails it does a <a href="functions.html#ustr_free">ustr_free()</a> and then sets the pointer to
 USTR("").

</td></tr><tr><td><strong>Note:</strong></td></tr><tr><td><p>
</p><p>  While the benifit is that you don't have to check for memory failure errors,
 if there is a memory failure and you have a non-default configuration the
 configuration will revert back to the default.


</td></tr></table><table width="90%"><tr><td class="sect"><h2><a id="Adding%20data%20to%20a%20Ustr">Adding data to a Ustr</a></h2>
</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_add_undef">ustr_add_undef()</a>
<br>Returns: Success or failure<br>Type: int
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a pointer to a <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: struct Ustr **
</td></tr><tr><td>Parameter<strong>[2]</strong>: Length of new undefined data<br>Type<strong>[2]</strong>: size_t
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  The <a href="design.html">Ustr string</a> is expanded (possibly reallocated) so that it can contain
 length (Parameter[2]) extra data, if the length is not zero the Ustr will
 be writable. Or it'll return <a href="constants.html#USTR_FALSE">USTR_FALSE</a> (zero) on failure.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_add_buf">ustr_add_buf()</a>
<br>Returns: Success or failure<br>Type: int
</td></tr><tr><td>Parameter<strong>[1]</strong>: Pointer to a pointer to a <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: struct Ustr **
</td></tr><tr><td>Parameter<strong>[2]</strong>: Pointer to data<br>Type<strong>[2]</strong>: const void *
</td></tr><tr><td>Parameter<strong>[3]</strong>: Length of data<br>Type<strong>[3]</strong>: size_t
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works as if you had called <a href="functions.html#ustr_add_undef">ustr_add_undef()</a> and then copied the
 data into the new undefined space.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_add_cstr">ustr_add_cstr()</a>
<br>Returns: Success or failure<br>Type: int 
</td></tr><tr><td>Parameter<strong>[1]</strong>: Pointer to a pointer to a <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: struct Ustr **
</td></tr><tr><td>Parameter<strong>[2]</strong>: Pointer to constant C-style string<br>Type<strong>[2]</strong>: const char *
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works as if you had called <a href="functions.html#ustr_add_buf">ustr_add_buf()</a> and passed strlen() as
 the length.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="USTR_ADD_OSTR">USTR_ADD_OSTR()</a>
<br>Returns: Success or failure<br>Type: int 
</td></tr><tr><td>Parameter<strong>[1]</strong>: Pointer to a pointer to a <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: struct Ustr **
</td></tr><tr><td>Parameter<strong>[2]</strong>: A constant C-style string<br>Type<strong>[2]</strong>: const char []
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works as if you had called <a href="functions.html#ustr_add_buf">ustr_add_buf()</a> and passed
 sizeof() - 1 as the length.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="USTR_ADD_OBJ">USTR_ADD_OBJ()</a>
<br>Returns: Success or failure<br>Type: int 
</td></tr><tr><td>Parameter<strong>[1]</strong>: Pointer to a pointer to a <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: struct Ustr **
</td></tr><tr><td>Parameter<strong>[2]</strong>: A symbol<br>Type<strong>[2]</strong>: ...
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works as if you had called <a href="functions.html#ustr_add_buf">ustr_add_buf()</a> and passed
 sizeof() as the length.

</td></tr><tr><td><strong>Note:</strong></td></tr><tr><td><p>
</p><p>  In most cases you'll want to use <a href="functions.html#USTR_ADD_OSTR">USTR_ADD_OSTR()</a>.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_add">ustr_add()</a>
<br>Returns: Success or failure<br>Type: int 
</td></tr><tr><td>Parameter<strong>[1]</strong>: Pointer to a pointer to a <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: struct Ustr **
</td></tr><tr><td>Parameter<strong>[2]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[2]</strong>: const struct Ustr *
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function mostly works as if you had called <a href="functions.html#ustr_add_buf">ustr_add_buf()</a> with the
 <a href="functions.html#ustr_cstr">ustr_cstr()</a> and <a href="functions.html#ustr_len">ustr_len()</a> values of the <a href="design.html">Ustr string</a> to be added.

</td></tr><tr><td><strong>Note:</strong></td></tr><tr><td><p>
</p><p>  If the <a href="design.html">Ustr string</a> is zero length and isn't writable this function may just
 add a reference, this is fine for Ustr strings that are "constant" because if
 the Ustr is read-only then the memory will not be written to.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_add_subustr">ustr_add_subustr()</a>
<br>Returns: Success or failure<br>Type: int 
</td></tr><tr><td>Parameter<strong>[1]</strong>: Pointer to a pointer to a <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: struct Ustr **
</td></tr><tr><td>Parameter<strong>[2]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[2]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[3]</strong>: Position in the Ustr<br>Type<strong>[3]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[4]</strong>: Length to add from the Ustr<br>Type<strong>[4]</strong>: size_t
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function mostly works as if you had called <a href="functions.html#ustr_add_buf">ustr_add_buf()</a> with the
 <a href="functions.html#ustr_cstr">ustr_cstr()</a> + position - 1 and length values of the <a href="design.html">Ustr string</a> to be added.
 The exception being if you add a ustr to itself, while only having a single
 reference count, the simple method would access a free'd ustr, but this
 function just works.

</td></tr><tr><td><strong>Note:</strong></td></tr><tr><td><p>
</p><p>  If the position is 1 and the length is the length of the <a href="design.html">Ustr string</a> then it
 just calls <a href="functions.html#ustr_add">ustr_add()</a>.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_add_rep_chr">ustr_add_rep_chr()</a>
<br>Returns: Success or failure<br>Type: int 
</td></tr><tr><td>Parameter<strong>[1]</strong>: Pointer to a pointer to a <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: struct Ustr **
</td></tr><tr><td>Parameter<strong>[2]</strong>: Byte value of data<br>Type<strong>[2]</strong>: char
</td></tr><tr><td>Parameter<strong>[3]</strong>: Length of bytes as data<br>Type<strong>[3]</strong>: size_t
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works as if you had called <a href="functions.html#ustr_add_undef">ustr_add_undef()</a> and then copied the
 byte value to each position.


</td></tr></table><table width="90%"><tr><td class="sect"><h2><a id="Setting%20a%20Ustr%20to%20some%20data">Setting a Ustr to some data</a></h2>
</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_set_undef">ustr_set_undef()</a>
<br>Returns: Success or failure <br>Type: int 
</td></tr><tr><td>Parameter<strong>[1]</strong>: Pointer to a pointer to a <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: struct Ustr **
</td></tr><tr><td>Parameter<strong>[2]</strong>:  size_t<br>Type<strong>[2]</strong>:  size_t
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works as if you had called <a href="functions.html#ustr_del">ustr_del()</a> for the entire string and
 the <a href="functions.html#ustr_add_undef">ustr_add_undef()</a>.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_set_empty">ustr_set_empty()</a>
<br>Returns: Success or failure<br>Type: int
</td></tr><tr><td>Parameter<strong>[1]</strong>: Pointer to a pointer to a <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: struct Ustr **
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works as if you had called <a href="functions.html#ustr_del">ustr_del()</a> for the entire string,
 however the string will be allocated if this completes.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_set_buf">ustr_set_buf()</a>
<br>Returns: Success or failure<br>Type: int
</td></tr><tr><td>Parameter<strong>[1]</strong>: Pointer to a pointer to a <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: struct Ustr **
</td></tr><tr><td>Parameter<strong>[2]</strong>: Buffer containting data<br>Type<strong>[2]</strong>:  const void *
</td></tr><tr><td>Parameter<strong>[3]</strong>: Length of Buffer<br>Type<strong>[3]</strong>: size_t
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works as if you had called <a href="functions.html#ustr_del">ustr_del()</a> for the entire string and
 the <a href="functions.html#ustr_add_buf">ustr_add_buf()</a>.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_set_cstr">ustr_set_cstr()</a>
<br>Returns: Success or failure<br>Type: int
</td></tr><tr><td>Parameter<strong>[1]</strong>: Pointer to a pointer to a <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: struct Ustr **
</td></tr><tr><td>Parameter<strong>[2]</strong>: A pointer to a constant C-style string<br>Type<strong>[2]</strong>: const char *
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works as if you had called <a href="functions.html#ustr_del">ustr_del()</a> for the entire string and
 then <a href="functions.html#ustr_add_cstr">ustr_add_cstr()</a>.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="USTR_SET_OSTR">USTR_SET_OSTR()</a>
<br>Returns: Success or failure<br>Type: int
</td></tr><tr><td>Parameter<strong>[1]</strong>: Pointer to a pointer to a <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: struct Ustr **
</td></tr><tr><td>Parameter<strong>[2]</strong>: A constant C-style string<br>Type<strong>[2]</strong>: const char []
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works as if you had called <a href="functions.html#ustr_del">ustr_del()</a> for the entire string and
 then <a href="functions.html#USTR_ADD_OSTR">USTR_ADD_OSTR()</a>.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="USTR_SET_OBJ">USTR_SET_OBJ()</a>
<br>Returns: Success or failure<br>Type: int
</td></tr><tr><td>Parameter<strong>[1]</strong>: Pointer to a pointer to a <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: struct Ustr **
</td></tr><tr><td>Parameter<strong>[2]</strong>: A symbol<br>Type<strong>[2]</strong>: ...
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works as if you had called <a href="functions.html#ustr_del">ustr_del()</a> for the entire string and
 then <a href="functions.html#USTR_ADD_OBJ">USTR_ADD_OBJ()</a>.

</td></tr><tr><td><strong>Note:</strong></td></tr><tr><td><p>
</p><p>  In most cases you'll want to use <a href="functions.html#USTR_SET_OSTR">USTR_SET_OSTR()</a>.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_set">ustr_set()</a>
<br>Returns: Success or failure<br>Type: int
</td></tr><tr><td>Parameter<strong>[1]</strong>: Pointer to a pointer to a <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: struct Ustr **
</td></tr><tr><td>Parameter<strong>[2]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[2]</strong>: const struct Ustr *
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works as if you had called <a href="functions.html#ustr_del">ustr_del()</a> for the entire string and
 the <a href="functions.html#ustr_add">ustr_add()</a>.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_set_subustr">ustr_set_subustr()</a>
<br>Returns: Success or failure<br>Type: int
</td></tr><tr><td>Parameter<strong>[1]</strong>: Pointer to a pointer to a <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: struct Ustr **
</td></tr><tr><td>Parameter<strong>[2]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[2]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[3]</strong>: Position in the Ustr<br>Type<strong>[3]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[4]</strong>: Length to set from the Ustr<br>Type<strong>[4]</strong>: size_t
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works as if you had called <a href="functions.html#ustr_del">ustr_del()</a> for the entire string and
 the <a href="functions.html#ustr_add_subustr">ustr_add_subustr()</a>. The exception being if you set a ustr to itself, while
 only having a single reference count, the simple method would access a
 free'd ustr data, but this function just works.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_set_rep_chr">ustr_set_rep_chr()</a>
<br>Returns: Success or failure<br>Type: int
</td></tr><tr><td>Parameter<strong>[1]</strong>: Pointer to a pointer to a <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: struct Ustr **
</td></tr><tr><td>Parameter<strong>[2]</strong>: Byte value of data<br>Type<strong>[2]</strong>: char
</td></tr><tr><td>Parameter<strong>[3]</strong>: Length of bytes as data<br>Type<strong>[3]</strong>: size_t
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works as if you had called <a href="functions.html#ustr_del">ustr_del()</a> for the entire string and
 the <a href="functions.html#ustr_add_rep_chr">ustr_add_rep_chr()</a>.


</td></tr></table><table width="90%"><tr><td class="sect"><h2><a id="Inserting%20data%20into%20a%20Ustr">Inserting data into a Ustr</a></h2>
</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_ins_undef">ustr_ins_undef()</a>
<br>Returns: Success or failure<br>Type: int
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a pointer to a <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: struct Ustr **
</td></tr><tr><td>Parameter<strong>[2]</strong>: Position after which the data should be added<br>Type<strong>[2]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[3]</strong>: Length of new undefined data<br>Type<strong>[3]</strong>: size_t
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  The <a href="design.html">Ustr string</a> is expanded (possibly reallocated) so that it can contain
 length (Parameter[2]) extra data, from after the required position. If the
 length is not zero the Ustr will be writable. Or it'll return
 <a href="constants.html#USTR_FALSE">USTR_FALSE</a> (zero) on failure. The data in the Ustr is moved as needed to put
 the new data at position (Parameter[2]) + 1.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_ins_buf">ustr_ins_buf()</a>
<br>Returns: Success or failure<br>Type: int
</td></tr><tr><td>Parameter<strong>[1]</strong>: Pointer to a pointer to a <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: struct Ustr **
</td></tr><tr><td>Parameter<strong>[2]</strong>: Position after which the data should be added<br>Type<strong>[2]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[3]</strong>: Pointer to data<br>Type<strong>[3]</strong>: const void *
</td></tr><tr><td>Parameter<strong>[4]</strong>: Length of data<br>Type<strong>[4]</strong>: size_t
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works as if you had called <a href="functions.html#ustr_ins_undef">ustr_ins_undef()</a> and then copied the
 data into the new undefined space.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_ins_cstr">ustr_ins_cstr()</a>
<br>Returns: Success or failure<br>Type: int 
</td></tr><tr><td>Parameter<strong>[1]</strong>: Pointer to a pointer to a <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: struct Ustr **
</td></tr><tr><td>Parameter<strong>[2]</strong>: Position after which the data should be added<br>Type<strong>[2]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[3]</strong>: Pointer to constant C-style string<br>Type<strong>[3]</strong>: const char *
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works as if you had called <a href="functions.html#ustr_ins_buf">ustr_ins_buf()</a> and passed strlen() as
 the length.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="USTR_INS_OSTR">USTR_INS_OSTR()</a>
<br>Returns: Success or failure<br>Type: int 
</td></tr><tr><td>Parameter<strong>[1]</strong>: Pointer to a pointer to a <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: struct Ustr **
</td></tr><tr><td>Parameter<strong>[2]</strong>: Position after which the data should be added<br>Type<strong>[2]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[3]</strong>: A constant C-style string<br>Type<strong>[3]</strong>: const char []
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works as if you had called <a href="functions.html#ustr_ins_buf">ustr_ins_buf()</a> and passed
 sizeof() - 1 as the length.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="USTR_INS_OBJ">USTR_INS_OBJ()</a>
<br>Returns: Success or failure<br>Type: int 
</td></tr><tr><td>Parameter<strong>[1]</strong>: Pointer to a pointer to a <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: struct Ustr **
</td></tr><tr><td>Parameter<strong>[2]</strong>: Position after which the data should be added<br>Type<strong>[2]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[3]</strong>: A symbol<br>Type<strong>[3]</strong>: ...
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works as if you had called <a href="functions.html#ustr_ins_buf">ustr_ins_buf()</a> and passed
 sizeof() as the length.

</td></tr><tr><td><strong>Note:</strong></td></tr><tr><td><p>
</p><p>  In most cases you'll want to use <a href="functions.html#USTR_INS_OSTR">USTR_INS_OSTR()</a>.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_ins">ustr_ins()</a>
<br>Returns: Success or failure<br>Type: int 
</td></tr><tr><td>Parameter<strong>[1]</strong>: Pointer to a pointer to a <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: struct Ustr **
</td></tr><tr><td>Parameter<strong>[2]</strong>: Position after which the data should be added<br>Type<strong>[2]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[3]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[3]</strong>: const struct Ustr *
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works as if you had called <a href="functions.html#ustr_ins_buf">ustr_ins_buf()</a> with the
 <a href="functions.html#ustr_cstr">ustr_cstr()</a> and <a href="functions.html#ustr_len">ustr_len()</a> values of the <a href="design.html">Ustr string</a> to be added.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_ins_subustr">ustr_ins_subustr()</a>
<br>Returns: Success or failure<br>Type: int 
</td></tr><tr><td>Parameter<strong>[1]</strong>: Pointer to a pointer to a <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: struct Ustr **
</td></tr><tr><td>Parameter<strong>[2]</strong>: Position after which the data should be added<br>Type<strong>[2]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[2]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[2]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[3]</strong>: Position in the Ustr<br>Type<strong>[3]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[4]</strong>: Length to ins from the Ustr<br>Type<strong>[4]</strong>: size_t
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function mostly as if you had called <a href="functions.html#ustr_ins_buf">ustr_ins_buf()</a> with the
 <a href="functions.html#ustr_cstr">ustr_cstr()</a> + position - 1 and length values of the <a href="design.html">Ustr string</a> to be insed.
 The exception being if you insert a ustr to itself, while only having a single
 reference count, the simple method would access a free'd ustr data, but this
 function just works.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_ins_rep_chr">ustr_ins_rep_chr()</a>
<br>Returns: Success or failure<br>Type: int 
</td></tr><tr><td>Parameter<strong>[1]</strong>: Pointer to a pointer to a <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: struct Ustr **
</td></tr><tr><td>Parameter<strong>[2]</strong>: Position after which the data should be added<br>Type<strong>[2]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[2]</strong>: Byte value of data<br>Type<strong>[2]</strong>: char
</td></tr><tr><td>Parameter<strong>[3]</strong>: Length of bytes as data<br>Type<strong>[3]</strong>: size_t
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works as if you had called <a href="functions.html#ustr_ins_undef">ustr_ins_undef()</a> and then copied the
 byte value to each position.


</td></tr></table><table width="90%"><tr><td class="sect"><h2><a id="Adding%2c%20duplicating%20and%20setting%20formatted%20data%20to%20a%20Ustr">Adding, duplicating and setting formatted data to a Ustr</a></h2>
</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_add_vfmt_lim">ustr_add_vfmt_lim()</a>
<br>Returns: Success or failure<br>Type: int 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a pointer to a <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: struct Ustr **
</td></tr><tr><td>Parameter<strong>[2]</strong>: Limit of data to add<br>Type<strong>[2]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[3]</strong>: A pointer to a constant C-style string<br>Type<strong>[3]</strong>: const char *
</td></tr><tr><td>Parameter<strong>[4]</strong>: Variable argument list variable, from va_start()<br>Type<strong>[4]</strong>: va_list
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works like calling the system vsnprintf() with the limit
 (Parameter[2]) as the limit to vsnprintf() and then calling <a href="functions.html#ustr_add_buf">ustr_add_buf()</a>.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_add_vfmt">ustr_add_vfmt()</a>
<br>Returns: Success or failure<br>Type: int 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a pointer to a <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: struct Ustr **
</td></tr><tr><td>Parameter<strong>[2]</strong>: A pointer to a constant C-style string<br>Type<strong>[2]</strong>: const char *
</td></tr><tr><td>Parameter<strong>[3]</strong>: Variable argument list variable, from va_start()<br>Type<strong>[3]</strong>: va_list
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works like calling the system vsnprintf() and then calling
 <a href="functions.html#ustr_add_buf">ustr_add_buf()</a>.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_add_fmt_lim">ustr_add_fmt_lim()</a>
<br>Returns: Success or failure<br>Type: int 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a pointer to a <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: struct Ustr **
</td></tr><tr><td>Parameter<strong>[2]</strong>: Limit of data to add<br>Type<strong>[2]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[3]</strong>: A pointer to a constant C-style string<br>Type<strong>[3]</strong>: const char *
</td></tr><tr><td>Parameter<strong>[4]</strong>: Options depending on value of Parameter[3]<br>Type<strong>[4]</strong>: ...
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works like calling the system snprintf() with the limit
 (Parameter[2]) as the limit to snprintf() and then calling <a href="functions.html#ustr_add_buf">ustr_add_buf()</a>.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_add_fmt">ustr_add_fmt()</a>
<br>Returns: Success or failure<br>Type: int 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a pointer to a <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: struct Ustr **
</td></tr><tr><td>Parameter<strong>[2]</strong>: A pointer to a constant C-style string<br>Type<strong>[2]</strong>: const char *
</td></tr><tr><td>Parameter<strong>[3]</strong>: Options depending on value of Parameter[2]<br>Type<strong>[3]</strong>: ...
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works like calling the system snprintf() and then calling
 <a href="functions.html#ustr_add_buf">ustr_add_buf()</a>.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_dup_vfmt_lim">ustr_dup_vfmt_lim()</a>
<br>Returns: Pointer to a <a href="design.html">Ustr string</a><br>Type: struct Ustr *
</td></tr><tr><td>Parameter<strong>[1]</strong>: Limit of data to dup<br>Type<strong>[1]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[2]</strong>: Pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[2]</strong>: const char *
</td></tr><tr><td>Parameter<strong>[3]</strong>: Variable argument list variable, from va_start()<br>Type<strong>[3]</strong>: va_list
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works like calling the system vsnprintf() with the limit
 (Parameter[2]) as the limit to vsnprintf() and then calling <a href="functions.html#ustr_dup_buf">ustr_dup_buf()</a>.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_dup_vfmt">ustr_dup_vfmt()</a>
<br>Returns: Pointer to a <a href="design.html">Ustr string</a><br>Type: struct Ustr *
</td></tr><tr><td>Parameter<strong>[1]</strong>: Limit of data to dup<br>Type<strong>[1]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[2]</strong>: Pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[2]</strong>: const char *
</td></tr><tr><td>Parameter<strong>[3]</strong>: Variable argument list variable, from va_start()<br>Type<strong>[3]</strong>: va_list
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works like calling the system vsnprintf() and then calling
 <a href="functions.html#ustr_dup_buf">ustr_dup_buf()</a>.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_dup_fmt_lim">ustr_dup_fmt_lim()</a>
<br>Returns: Pointer to a <a href="design.html">Ustr string</a><br>Type: struct Ustr *
</td></tr><tr><td>Parameter<strong>[1]</strong>: Limit of data to dup<br>Type<strong>[1]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[2]</strong>: Pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[2]</strong>: const char *
</td></tr><tr><td>Parameter<strong>[3]</strong>: Options depending on value of Parameter[2]<br>Type<strong>[3]</strong>: ...
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works like calling the system snprintf() with the limit
 (Parameter[2]) as the limit to snprintf() and then calling <a href="functions.html#ustr_dup_buf">ustr_dup_buf()</a>.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_dup_fmt">ustr_dup_fmt()</a>
<br>Returns: Pointer to a <a href="design.html">Ustr string</a><br>Type: struct Ustr *
</td></tr><tr><td>Parameter<strong>[1]</strong>: Pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: const char *
</td></tr><tr><td>Parameter<strong>[2]</strong>: Options depending on value of Parameter[1]<br>Type<strong>[2]</strong>: ...
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works like calling the system snprintf() and then calling
 <a href="functions.html#ustr_dup_buf">ustr_dup_buf()</a>.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_dupx_fmt_lim">ustr_dupx_fmt_lim()</a>
<br>Returns: Pointer to a <a href="design.html">Ustr string</a><br>Type: struct Ustr *
</td></tr><tr><td>Parameter<strong>[1]</strong>: Size of allocated storage<br>Type<strong>[1]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[2]</strong>: Number of bytes to use for reference count<br>Type<strong>[2]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[3]</strong>: Exact memory allocations<br>Type<strong>[3]</strong>: int
</td></tr><tr><td>Parameter<strong>[4]</strong>: ENOMEM, memory error flag<br>Type<strong>[4]</strong>: int
</td></tr><tr><td>Parameter<strong>[5]</strong>: Limit of data to dup<br>Type<strong>[5]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[6]</strong>: Pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[6]</strong>: const char *
</td></tr><tr><td>Parameter<strong>[7]</strong>: Options depending on value of Parameter[6]<br>Type<strong>[7]</strong>: ...
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works like calling the system snprintf() with the limit
 (Parameter[2]) as the limit to snprintf() and then calling <a href="functions.html#ustr_dupx_buf">ustr_dupx_buf()</a>.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_dupx_fmt">ustr_dupx_fmt()</a>
<br>Returns: Pointer to a <a href="design.html">Ustr string</a><br>Type: struct Ustr *
</td></tr><tr><td>Parameter<strong>[1]</strong>: Size of allocated storage<br>Type<strong>[1]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[2]</strong>: Number of bytes to use for reference count<br>Type<strong>[2]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[3]</strong>: Exact memory allocations<br>Type<strong>[3]</strong>: int
</td></tr><tr><td>Parameter<strong>[4]</strong>: ENOMEM, memory error flag<br>Type<strong>[4]</strong>: int
</td></tr><tr><td>Parameter<strong>[5]</strong>: Pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[5]</strong>: const char *
</td></tr><tr><td>Parameter<strong>[6]</strong>: Options depending on value of Parameter[5]<br>Type<strong>[6]</strong>: ...
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works like calling the system snprintf() and then calling
 <a href="functions.html#ustr_dup_bufx">ustr_dup_bufx()</a>.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_set_vfmt_lim">ustr_set_vfmt_lim()</a>
<br>Returns: Success or failure<br>Type: int 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a pointer to a <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: struct Ustr **
</td></tr><tr><td>Parameter<strong>[2]</strong>: Limit of data to set<br>Type<strong>[2]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[3]</strong>: A pointer to a constant C-style string<br>Type<strong>[3]</strong>: const char *
</td></tr><tr><td>Parameter<strong>[4]</strong>: Variable argument list variable, from va_start()<br>Type<strong>[4]</strong>: va_list
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works like calling <a href="functions.html#ustr_del">ustr_del()</a> for all the data and then
 <a href="functions.html#ustr_add_vfmt_lim">ustr_add_vfmt_lim()</a>.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_set_vfmt">ustr_set_vfmt()</a>
<br>Returns: Success or failure<br>Type: int 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a pointer to a <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: struct Ustr **
</td></tr><tr><td>Parameter<strong>[2]</strong>: A pointer to a constant C-style string<br>Type<strong>[2]</strong>: const char *
</td></tr><tr><td>Parameter<strong>[3]</strong>: Variable argument list variable, from va_start()<br>Type<strong>[3]</strong>: va_list
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works like calling <a href="functions.html#ustr_del">ustr_del()</a> for all the data and then
 <a href="functions.html#ustr_add_vfmt">ustr_add_vfmt()</a>.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_set_fmt_lim">ustr_set_fmt_lim()</a>
<br>Returns: Success or failure<br>Type: int 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a pointer to a <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: struct Ustr **
</td></tr><tr><td>Parameter<strong>[2]</strong>: Limit of data to set<br>Type<strong>[2]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[3]</strong>: A pointer to a constant C-style string<br>Type<strong>[3]</strong>: const char *
</td></tr><tr><td>Parameter<strong>[4]</strong>: Options depending on value of Parameter[3]<br>Type<strong>[4]</strong>: ...
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works like calling <a href="functions.html#ustr_del">ustr_del()</a> for all the data and then
 <a href="functions.html#ustr_add_fmt_lim">ustr_add_fmt_lim()</a>.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_set_fmt">ustr_set_fmt()</a>
<br>Returns: Success or failure<br>Type: int 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a pointer to a <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: struct Ustr **
</td></tr><tr><td>Parameter<strong>[2]</strong>: A pointer to a constant C-style string<br>Type<strong>[2]</strong>: const char *
</td></tr><tr><td>Parameter<strong>[3]</strong>: Options depending on value of Parameter[2]<br>Type<strong>[3]</strong>: ...
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works like calling <a href="functions.html#ustr_del">ustr_del()</a> for all the data and then
 <a href="functions.html#ustr_add_fmt">ustr_add_fmt()</a>.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_ins_vfmt_lim">ustr_ins_vfmt_lim()</a>
<br>Returns: Success or failure<br>Type: int 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a pointer to a <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: struct Ustr **
</td></tr><tr><td>Parameter<strong>[2]</strong>: Position after which the data should be added<br>Type<strong>[2]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[3]</strong>: Limit of data to insert<br>Type<strong>[3]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[4]</strong>: A pointer to a constant C-style string<br>Type<strong>[4]</strong>: const char *
</td></tr><tr><td>Parameter<strong>[5]</strong>: Variable argument list variable, from va_start()<br>Type<strong>[5]</strong>: va_list
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works like calling the system vsnprintf() with the limit
 (Parameter[3]) as the limit to vsnprintf() and then calling <a href="functions.html#ustr_ins_buf">ustr_ins_buf()</a>.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_ins_vfmt">ustr_ins_vfmt()</a>
<br>Returns: Success or failure<br>Type: int 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a pointer to a <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: struct Ustr **
</td></tr><tr><td>Parameter<strong>[2]</strong>: Position after which the data should be added<br>Type<strong>[2]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[3]</strong>: A pointer to a constant C-style string<br>Type<strong>[3]</strong>: const char *
</td></tr><tr><td>Parameter<strong>[4]</strong>: Variable argument list variable, from va_start()<br>Type<strong>[4]</strong>: va_list
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works like calling the system vsnprintf() and then calling
 <a href="functions.html#ustr_ins_buf">ustr_ins_buf()</a>.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_ins_fmt_lim">ustr_ins_fmt_lim()</a>
<br>Returns: Success or failure<br>Type: int 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a pointer to a <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: struct Ustr **
</td></tr><tr><td>Parameter<strong>[2]</strong>: Position after which the data should be added<br>Type<strong>[2]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[3]</strong>: Limit of data to insert<br>Type<strong>[3]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[4]</strong>: A pointer to a constant C-style string<br>Type<strong>[4]</strong>: const char *
</td></tr><tr><td>Parameter<strong>[5]</strong>: Options depending on value of Parameter[4]<br>Type<strong>[5]</strong>: ...
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works like calling the system snprintf() with the limit
 (Parameter[3]) as the limit to snprintf() and then calling <a href="functions.html#ustr_ins_buf">ustr_ins_buf()</a>.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_ins_fmt">ustr_ins_fmt()</a>
<br>Returns: Success or failure<br>Type: int 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a pointer to a <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: struct Ustr **
</td></tr><tr><td>Parameter<strong>[2]</strong>: Position after which the data should be added<br>Type<strong>[2]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[3]</strong>: A pointer to a constant C-style string<br>Type<strong>[3]</strong>: const char *
</td></tr><tr><td>Parameter<strong>[4]</strong>: Options depending on value of Parameter[3]<br>Type<strong>[4]</strong>: ...
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works like calling the system snprintf() and then calling
 <a href="functions.html#ustr_ins_buf">ustr_ins_buf()</a>.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_sub_vfmt_lim">ustr_sub_vfmt_lim()</a>
<br>Returns: Success or failure<br>Type: int 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a pointer to a <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: struct Ustr **
</td></tr><tr><td>Parameter<strong>[2]</strong>: Position where to start substitution<br>Type<strong>[2]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[3]</strong>: Limit of data to substitute<br>Type<strong>[3]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[4]</strong>: A pointer to a constant C-style string<br>Type<strong>[4]</strong>: const char *
</td></tr><tr><td>Parameter<strong>[5]</strong>: Variable argument list variable, from va_start()<br>Type<strong>[5]</strong>: va_list
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works like calling the system vsnprintf() with the limit
 (Parameter[3]) as the limit to vsnprintf() and then calling <a href="functions.html#ustr_sub_buf">ustr_sub_buf()</a>.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_sub_vfmt">ustr_sub_vfmt()</a>
<br>Returns: Success or failure<br>Type: int 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a pointer to a <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: struct Ustr **
</td></tr><tr><td>Parameter<strong>[2]</strong>: Position where to start substitution<br>Type<strong>[2]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[3]</strong>: A pointer to a constant C-style string<br>Type<strong>[3]</strong>: const char *
</td></tr><tr><td>Parameter<strong>[4]</strong>: Variable argument list variable, from va_start()<br>Type<strong>[4]</strong>: va_list
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works like calling the system vsnprintf() and then calling
 <a href="functions.html#ustr_sub_buf">ustr_sub_buf()</a>.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_sub_fmt_lim">ustr_sub_fmt_lim()</a>
<br>Returns: Success or failure<br>Type: int 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a pointer to a <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: struct Ustr **
</td></tr><tr><td>Parameter<strong>[2]</strong>: Position where to start substitution<br>Type<strong>[2]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[3]</strong>: Limit of data to substitute<br>Type<strong>[3]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[4]</strong>: A pointer to a constant C-style string<br>Type<strong>[4]</strong>: const char *
</td></tr><tr><td>Parameter<strong>[5]</strong>: Options depending on value of Parameter[4]<br>Type<strong>[5]</strong>: ...
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works like calling the system snprintf() with the limit
 (Parameter[3]) as the limit to snprintf() and then calling <a href="functions.html#ustr_sub_buf">ustr_sub_buf()</a>.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_sub_fmt">ustr_sub_fmt()</a>
<br>Returns: Success or failure<br>Type: int 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a pointer to a <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: struct Ustr **
</td></tr><tr><td>Parameter<strong>[2]</strong>: Position where to start substitution<br>Type<strong>[2]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[3]</strong>: A pointer to a constant C-style string<br>Type<strong>[3]</strong>: const char *
</td></tr><tr><td>Parameter<strong>[4]</strong>: Options depending on value of Parameter[3]<br>Type<strong>[4]</strong>: ...
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works like calling the system snprintf() and then calling
 <a href="functions.html#ustr_sub_buf">ustr_sub_buf()</a>.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_sc_sub_vfmt_lim">ustr_sc_sub_vfmt_lim()</a>
<br>Returns: Success or failure<br>Type: int 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a pointer to a <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: struct Ustr **
</td></tr><tr><td>Parameter<strong>[2]</strong>: Position where to start substitution<br>Type<strong>[2]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[3]</strong>: Length of substitution<br>Type<strong>[3]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[4]</strong>: Limit of data to substitute<br>Type<strong>[4]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[5]</strong>: A pointer to a constant C-style string<br>Type<strong>[5]</strong>: const char *
</td></tr><tr><td>Parameter<strong>[6]</strong>: Variable argument list variable, from va_start()<br>Type<strong>[6]</strong>: va_list
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works like calling the system vsnprintf() with the limit
 (Parameter[4]) as the limit to vsnprintf() and then calling <a href="functions.html#ustr_sc_sub_buf">ustr_sc_sub_buf()</a>.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_sc_sub_vfmt">ustr_sc_sub_vfmt()</a>
<br>Returns: Success or failure<br>Type: int 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a pointer to a <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: struct Ustr **
</td></tr><tr><td>Parameter<strong>[2]</strong>: Position where to start substitution<br>Type<strong>[2]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[3]</strong>: Length of substitution<br>Type<strong>[3]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[4]</strong>: A pointer to a constant C-style string<br>Type<strong>[4]</strong>: const char *
</td></tr><tr><td>Parameter<strong>[5]</strong>: Variable argument list variable, from va_start()<br>Type<strong>[5]</strong>: va_list
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works like calling the system vsnprintf() and then calling
 <a href="functions.html#ustr_sc_sub_buf">ustr_sc_sub_buf()</a>.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_sc_sub_fmt_lim">ustr_sc_sub_fmt_lim()</a>
<br>Returns: Success or failure<br>Type: int 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a pointer to a <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: struct Ustr **
</td></tr><tr><td>Parameter<strong>[2]</strong>: Position where to start substitution<br>Type<strong>[2]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[3]</strong>: Length of substitution<br>Type<strong>[3]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[4]</strong>: Limit of data to substitute<br>Type<strong>[4]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[5]</strong>: A pointer to a constant C-style string<br>Type<strong>[5]</strong>: const char *
</td></tr><tr><td>Parameter<strong>[6]</strong>: Options depending on value of Parameter[5]<br>Type<strong>[6]</strong>: ...
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works like calling the system snprintf() with the limit
 (Parameter[3]) as the limit to snprintf() and then calling <a href="functions.html#ustr_sc_sub_buf">ustr_sc_sub_buf()</a>.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_sc_sub_fmt">ustr_sc_sub_fmt()</a>
<br>Returns: Success or failure<br>Type: int 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a pointer to a <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: struct Ustr **
</td></tr><tr><td>Parameter<strong>[2]</strong>: Position where to start substitution<br>Type<strong>[2]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[3]</strong>: Length of substitution<br>Type<strong>[3]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[4]</strong>: A pointer to a constant C-style string<br>Type<strong>[4]</strong>: const char *
</td></tr><tr><td>Parameter<strong>[5]</strong>: Options depending on value of Parameter[5]<br>Type<strong>[5]</strong>: ...
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works like calling the system snprintf() and then calling
 <a href="functions.html#ustr_sc_sub_buf">ustr_sc_sub_buf()</a>.


</td></tr></table><table width="90%"><tr><td class="sect"><h2><a id="Accessing%20the%20%22variables%22%20of%20a%20Ustr">Accessing the "variables" of a Ustr</a></h2>
</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_len">ustr_len()</a>
<br>Returns: The length of the Ustr<br>Type: size_t 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: const struct Ustr *
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function returns the length of the data within the Ustr, much like
 strlen() but without getting the value wrong in the case of extra NIL bytes.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_cstr">ustr_cstr()</a>
<br>Returns: Read-only pointer to the start of data in the Ustr<br>Type: const char *
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: const struct Ustr *
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function returns a read-only pointer to the start of the data of the
 <a href="design.html">Ustr string</a>. Due to there always being a terminating NIL byte in a Ustr, this
 is also a valid C-style string.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_wstr">ustr_wstr()</a>
<br>Returns: Writable pointer to the start of data in the Ustr, or NULL<br>Type: char *
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: struct Ustr *
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function returns a writable pointer to the start of the data of the
 <a href="design.html">Ustr string</a>. Due to there always being a terminating NIL byte in a Ustr, this
 is also a valid C-style string.
</p><p>  If the ustr is read-only (<a href="functions.html#ustr_ro">ustr_ro()</a> == <a href="constants.html#USTR_TRUE">USTR_TRUE</a>) then this function will
 return NULL.

</td></tr><tr><td><strong>Note:</strong></td></tr><tr><td><p>
</p><p>  Unless the string is owned (<a href="functions.html#ustr_owner">ustr_owner()</a> == <a href="constants.html#USTR_TRUE">USTR_TRUE</a>) it can be a very bad
 idea to use this to change data, as then all references will be updated. See
 <a href="functions.html#ustr_sc_wstr">ustr_sc_wstr()</a>.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_alloc">ustr_alloc()</a>
<br>Returns: A boolean flag of either <a href="constants.html#USTR_TRUE">USTR_TRUE</a> or USTR_FALSE<br>Type: int
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: const struct Ustr *
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function says if the Ustr is currently in allocated storage.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_exact">ustr_exact()</a>
<br>Returns: A boolean flag of either <a href="constants.html#USTR_TRUE">USTR_TRUE</a> or USTR_FALSE<br>Type: int
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: const struct Ustr *
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function says if the Ustr is doing exact allocations, so as the Ustr
 grows it will only have storage allocated exactly as required and not in half
 powers of two.

</td></tr><tr><td><strong>Note:</strong></td></tr><tr><td><p>
</p><p>  This will always be <a href="constants.html#USTR_FALSE">USTR_FALSE</a> for read-only Ustr strings
 (<a href="functions.html#ustr_ro">ustr_ro()</a> == <a href="constants.html#USTR_TRUE">USTR_TRUE</a>), even though the default may be to used exact sized
 allocations when  adding data to them etc.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_sized">ustr_sized()</a>
<br>Returns: A boolean flag of either <a href="constants.html#USTR_TRUE">USTR_TRUE</a> or USTR_FALSE<br>Type: int 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: const struct Ustr *
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function says if the Ustr stores an explicit allocation size, if not
 the size is implied as the next highest half power of two.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_ro">ustr_ro()</a>
<br>Returns: A boolean flag of either <a href="constants.html#USTR_TRUE">USTR_TRUE</a> or USTR_FALSE<br>Type: int
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: const struct Ustr *
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function says if the Ustr is current in read-only storage.
</p><p>  Read-only storage is not writable but can be referenced via. <a href="functions.html#ustr_dup">ustr_dup()</a> an
 infinite amount of times.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_fixed">ustr_fixed()</a>
<br>Returns: A boolean flag of either <a href="constants.html#USTR_TRUE">USTR_TRUE</a> or USTR_FALSE<br>Type: int 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: const struct Ustr *
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function says if the Ustr is current in fixed size storage.
</p><p>  Fixed size storage is writable but cannot be referenced.

</td></tr><tr><td><strong>Note:</strong></td></tr><tr><td><p>
</p><p>  Fixed size storage always explicitly stores the size of the storage.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_enomem">ustr_enomem()</a>
<br>Returns: A boolean flag of either <a href="constants.html#USTR_TRUE">USTR_TRUE</a> or USTR_FALSE<br>Type: int 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: const struct Ustr *
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function just returns the value of the user settable flag in the Ustr. It
 can be set via. <a href="functions.html#ustr_setf_enomem_err">ustr_setf_enomem_err()</a> and cleared by <a href="functions.html#ustr_setf_enomem_clr">ustr_setf_enomem_clr()</a>.
</p><p>  This function is automatically set to on whever a memory allocation failure
 happens for a Ustr.

</td></tr><tr><td><strong>Note:</strong></td></tr><tr><td><p>
</p><p>  If a Ustr is referenced multiple times, <a href="functions.html#ustr_setf_enomem_err">ustr_setf_enomem_err()</a> will fail.
</p><p>  This always fails for Ustr's in read-only storage.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_shared">ustr_shared()</a>
<br>Returns: A boolean flag of either <a href="constants.html#USTR_TRUE">USTR_TRUE</a> or USTR_FALSE<br>Type: int 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: const struct Ustr *
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function says if the Ustr is in the &quot;shared&quot; mode. It can be set via.
 <a href="functions.html#ustr_setf_shared">ustr_setf_shared()</a> and cleared by <a href="functions.html#ustr_setf_owner">ustr_setf_owner()</a> on allocated Ustr's.
</p><p>  Shared mode means that a Ustr can be referenced and unreferenced an infinite
 number of times.

</td></tr><tr><td><strong>Note:</strong></td></tr><tr><td><p>
</p><p>  This always succeeds for Ustr's in read-only storage.
</p><p>  This always fails for Ustr's in fixed size storage.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_limited">ustr_limited()</a>
<br>Returns: A boolean flag of either <a href="constants.html#USTR_TRUE">USTR_TRUE</a> or USTR_FALSE<br>Type: int 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: const struct Ustr *
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function says if the Ustr is currently in fixed size storage and cannot
 move to allocated storage.

</td></tr><tr><td><strong>Note:</strong></td></tr><tr><td><p>
</p><p>  This always fails for Ustr's in allocated storage.
</p><p>  This always fails for Ustr's in read-only storage.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_owner">ustr_owner()</a>
<br>Returns: A boolean flag of either <a href="constants.html#USTR_TRUE">USTR_TRUE</a> or USTR_FALSE<br>Type: int 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: const struct Ustr *
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function says if there is only a single reference to the <a href="design.html">Ustr string</a>.

</td></tr><tr><td><strong>Note:</strong></td></tr><tr><td><p>
</p><p>  This always fails for Ustr's in read-only storage.
</p><p>  This always succeeds for Ustr's in fixed size storage.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_size">ustr_size()</a>
<br>Returns: size_t <br>Type: size_t 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: const struct Ustr *
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function calculates the maximum amount of data that could be stored (Ie.
 the max <a href="functions.html#ustr_len">ustr_len()</a>) without having to re-size the <a href="design.html">Ustr string</a>.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_size_alloc">ustr_size_alloc()</a>
<br>Returns: size_t <br>Type: size_t 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: const struct Ustr *
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function returns the size of the storage for the Ustr.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_size_overhead">ustr_size_overhead()</a>
<br>Returns: size_t <br>Type: size_t 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: const struct Ustr *
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function returns the difference between the size of the storage and the
 maximum amount of data that could be stored without having to re-size the Ustr
 string.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_conf">ustr_conf()</a>
<br>Returns: Nothing<br>Type: void 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[2]</strong>: Return size allocated number<br>Type<strong>[2]</strong>: size_t *
</td></tr><tr><td>Parameter<strong>[3]</strong>: Return number of bytes used in the reference count<br>Type<strong>[3]</strong>: size_t *
</td></tr><tr><td>Parameter<strong>[4]</strong>: Return exact allocations flag<br>Type<strong>[4]</strong>: int *
</td></tr><tr><td>Parameter<strong>[5]</strong>: Return number of bytes used in the length<br>Type<strong>[5]</strong>: size_t *
</td></tr><tr><td>Parameter<strong>[5]</strong>: Return number of references to this Ustr<br>Type<strong>[5]</strong>: size_t *
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function gives the configuration of the current Ustr needed to duplicate
 it via. the ustr_dupx_*() functions. It also gives the number of bytes used
 for the length and the number of references, which are mainly informational.

</td></tr><tr><td><strong>Note:</strong></td></tr><tr><td><p>
</p><p>  This function differs from calling the <a href="functions.html#ustr_exact">ustr_exact()</a> etc. functions in that
 it returns the global options if this Ustr isn't allocated, thus telling you
 what the configuration would be if the Ustr was turned into an allocated Ustr
 by adding data etc.
</p><p>  Zero references for an allocated Ustr with a non-zero number of bytes for a
 reference count means it's in "shared" mode).


</td></tr></table><table width="90%"><tr><td class="sect"><h2><a id="Setting%20the%20%22flags%22%20of%20a%20Ustr">Setting the "flags" of a Ustr</a></h2>
</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_setf_enomem_err">ustr_setf_enomem_err()</a>
<br>Returns: Success or failure<br>Type: int 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: struct Ustr *
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function sets the enomem flag, which can be observed via. the
 <a href="functions.html#ustr_enomem">ustr_enomem()</a> function.
</p><p>  The implication of setting this flag is that a memory error has occured in a
 previous function call on this Ustr.

</td></tr><tr><td><strong>Note:</strong></td></tr><tr><td><p>
</p><p>  This function fails if <a href="functions.html#ustr_owner">ustr_owner()</a> fails for the Ustr.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_setf_enomem_clr">ustr_setf_enomem_clr()</a>
<br>Returns: Success or failure<br>Type: int 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: struct Ustr *
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function clears the enomem flag, which can be observed via. the
 <a href="functions.html#ustr_enomem">ustr_enomem()</a> function.
</p><p>  The implication of this flag being set is that a memory error has occured in
 a previous function call on this Ustr, so on clearing the flag you should
 know you have brought the Ustr back to a known state.

</td></tr><tr><td><strong>Note:</strong></td></tr><tr><td><p>
</p><p>  This function fails if <a href="functions.html#ustr_owner">ustr_owner()</a> fails for the Ustr.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_setf_share">ustr_setf_share()</a>
<br>Returns: Success or failure<br>Type: int 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: struct Ustr *
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function sets the shared mode, which can be observed via. the
 <a href="functions.html#ustr_shared">ustr_shared()</a> function.
</p><p>  This is used on a Ustr so that it can have more references than it is able
 to hold in it's reference count. After this call the Ustr can be referenced and
 unreferenced an infinite number of times.

</td></tr><tr><td><strong>Note:</strong></td></tr><tr><td><p>
</p><p>  After this call the Ustr will never be deleted until <a href="functions.html#ustr_setf_owner">ustr_setf_owner()</a> is
 called.
</p><p>  This function fails if <a href="functions.html#ustr_alloc">ustr_alloc()</a> fails for the Ustr.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_setf_owner">ustr_setf_owner()</a>
<br>Returns: Success or failure<br>Type: int 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: struct Ustr *
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function removes the shared mode, which can be observed via. the
 <a href="functions.html#ustr_shared">ustr_shared()</a> function.
</p><p>  This is used so that a Ustr in shared mode can be free'd.

</td></tr><tr><td><strong>Note:</strong></td></tr><tr><td><p>
</p><p>  This function fails if <a href="functions.html#ustr_alloc">ustr_alloc()</a> fails for the Ustr.


</td></tr></table><table width="90%"><tr><td class="sect"><h2><a id="Comparing%20data%20in%20a%20Ustr">Comparing data in a Ustr</a></h2>
</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_cmp_buf">ustr_cmp_buf()</a>
<br>Returns: Less then zero, zero or greater than zero depending on comparison<br>Type: int 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[2]</strong>: A pointer to constant bytes, to compare<br>Type<strong>[2]</strong>: const void *
</td></tr><tr><td>Parameter<strong>[3]</strong>: Length of comparison bytes<br>Type<strong>[3]</strong>: size_t
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works like memcmp() on the Ustr and the passed data.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_cmp">ustr_cmp()</a>
<br>Returns: Less then zero, zero or greater than zero depending on comparison<br>Type: int 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[2]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[2]</strong>: const struct Ustr *
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works like <a href="functions.html#ustr_cmp_buf">ustr_cmp_buf()</a> but with the data from <a href="functions.html#ustr_cstr">ustr_cstr()</a>
 and the length from <a href="functions.html#ustr_len">ustr_len()</a>.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_cmp_subustr">ustr_cmp_subustr()</a>
<br>Returns: Less then zero, zero or greater than zero depending on comparison<br>Type: int 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[2]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[2]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[3]</strong>: Position in the Ustr<br>Type<strong>[3]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[4]</strong>: Length to compare from the Ustr<br>Type<strong>[4]</strong>: size_t
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works like <a href="functions.html#ustr_cmp">ustr_cmp()</a> but with a limit on the data and length.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_cmp_cstr">ustr_cmp_cstr()</a>
<br>Returns: Less then zero, zero or greater than zero depending on comparison<br>Type: int 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[2]</strong>: A pointer to a constant C-style string<br>Type<strong>[2]</strong>: const char *
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works like <a href="functions.html#ustr_cmp_buf">ustr_cmp_buf()</a> but with a length from strlen().


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_cmp_fast_buf">ustr_cmp_fast_buf()</a>
<br>Returns: Less then zero, zero or greater than zero depending on comparison<br>Type: int 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[2]</strong>: A pointer to constant bytes, to compare<br>Type<strong>[2]</strong>: const void *
</td></tr><tr><td>Parameter<strong>[3]</strong>: Length of comparison bytes<br>Type<strong>[3]</strong>: size_t
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works like <a href="functions.html#ustr_cmp_buf">ustr_cmp_buf()</a> but the order of comparison is
 optimized for speed, but is much less friendly to humans.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_cmp_fast">ustr_cmp_fast()</a>
<br>Returns: Less then zero, zero or greater than zero depending on comparison<br>Type: int 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[2]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[2]</strong>: const struct Ustr *
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works like <a href="functions.html#ustr_cmp_fast_buf">ustr_cmp_fast_buf()</a> but with the data from
 <a href="functions.html#ustr_cstr">ustr_cstr()</a> and the length from <a href="functions.html#ustr_len">ustr_len()</a>.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_cmp_fast_subustr">ustr_cmp_fast_subustr()</a>
<br>Returns: Less then zero, zero or greater than zero depending on comparison<br>Type: int 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[2]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[2]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[3]</strong>: Position in the Ustr<br>Type<strong>[3]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[4]</strong>: Length to compare from the Ustr<br>Type<strong>[4]</strong>: size_t
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works like <a href="functions.html#ustr_cmp_fast">ustr_cmp_fast()</a> but with a limit on the data and
 length.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_cmp_fast_cstr">ustr_cmp_fast_cstr()</a>
<br>Returns: Less then zero, zero or greater than zero depending on comparison<br>Type: int 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[2]</strong>: A pointer to a constant C-style string<br>Type<strong>[2]</strong>: const char *
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works like <a href="functions.html#ustr_cmp_fast_buf">ustr_cmp_fast_buf()</a> but with a length from strlen().


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_cmp_case_buf">ustr_cmp_case_buf()</a>
<br>Returns: Less then zero, zero or greater than zero depending on comparison<br>Type: int 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[2]</strong>: A pointer to constant bytes, to compare<br>Type<strong>[2]</strong>: const void *
</td></tr><tr><td>Parameter<strong>[3]</strong>: Length of comparison bytes<br>Type<strong>[3]</strong>: size_t
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works like <a href="functions.html#ustr_cmp_buf">ustr_cmp_buf()</a> but the order of comparison ignores
 ASCII case.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_cmp_case">ustr_cmp_case()</a>
<br>Returns: Less then zero, zero or greater than zero depending on comparison<br>Type: int 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[2]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[2]</strong>: const struct Ustr *
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works like <a href="functions.html#ustr_cmp_case_buf">ustr_cmp_case_buf()</a> but with the data from
 <a href="functions.html#ustr_cstr">ustr_cstr()</a> and the length from <a href="functions.html#ustr_len">ustr_len()</a>.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_cmp_case_subustr">ustr_cmp_case_subustr()</a>
<br>Returns: Less then zero, zero or greater than zero depending on comparison<br>Type: int 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[2]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[2]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[3]</strong>: Position in the Ustr<br>Type<strong>[3]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[4]</strong>: Length to compare from the Ustr<br>Type<strong>[4]</strong>: size_t
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works like <a href="functions.html#ustr_cmp_case">ustr_cmp_case()</a> but with a limit on the data and
 length.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_cmp_case_cstr">ustr_cmp_case_cstr()</a>
<br>Returns: Less then zero, zero or greater than zero depending on comparison<br>Type: int 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[2]</strong>: A pointer to a constant C-style string<br>Type<strong>[2]</strong>: const char *
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works like <a href="functions.html#ustr_cmp_case_buf">ustr_cmp_case_buf()</a> but with a length from strlen().


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_cmp_eq">ustr_cmp_eq()</a>
<br>Returns: Success or failure<br>Type: int 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[2]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[2]</strong>: const struct Ustr *
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works like comparing <a href="functions.html#ustr_cmp">ustr_cmp()</a> against 0.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_cmp_buf_eq">ustr_cmp_buf_eq()</a>
<br>Returns: Success or failure<br>Type: int 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[2]</strong>: A pointer to constant bytes, to compare<br>Type<strong>[2]</strong>: const void *
</td></tr><tr><td>Parameter<strong>[3]</strong>: Length of comparison bytes<br>Type<strong>[3]</strong>: size_t
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works like comparing <a href="functions.html#ustr_cmp_buf">ustr_cmp_buf()</a> against 0.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_cmp_subustr_eq">ustr_cmp_subustr_eq()</a>
<br>Returns: Success or failure<br>Type: int 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[2]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[2]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[3]</strong>: Position in the Ustr<br>Type<strong>[3]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[4]</strong>: Length to compare from the Ustr<br>Type<strong>[4]</strong>: size_t
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works like comparing <a href="functions.html#ustr_cmp_subustr">ustr_cmp_subustr()</a> against 0.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_cmp_cstr_eq">ustr_cmp_cstr_eq()</a>
<br>Returns: Success or failure<br>Type: int 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[2]</strong>: A pointer to a constant C-style string<br>Type<strong>[2]</strong>: const char *
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works like comparing <a href="functions.html#ustr_cmp_cstr">ustr_cmp_cstr()</a> against 0.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_cmp_case_eq">ustr_cmp_case_eq()</a>
<br>Returns: Success or failure<br>Type: int 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[2]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[2]</strong>: const struct Ustr *
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works like comparing <a href="functions.html#ustr_cmp_case">ustr_cmp_case()</a> against 0.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_cmp_case_buf_eq">ustr_cmp_case_buf_eq()</a>
<br>Returns: Success or failure<br>Type: int 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[2]</strong>: A pointer to constant bytes, to compare<br>Type<strong>[2]</strong>: const void *
</td></tr><tr><td>Parameter<strong>[3]</strong>: Length of comparison bytes<br>Type<strong>[3]</strong>: size_t
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works like comparing <a href="functions.html#ustr_cmp_case_buf">ustr_cmp_case_buf()</a> against 0.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_cmp_case_subustr_eq">ustr_cmp_case_subustr_eq()</a>
<br>Returns: Success or failure<br>Type: int 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[2]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[2]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[3]</strong>: Position in the Ustr<br>Type<strong>[3]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[4]</strong>: Length to compare from the Ustr<br>Type<strong>[4]</strong>: size_t
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works like comparing <a href="functions.html#ustr_cmp_case_subustr">ustr_cmp_case_subustr()</a> against 0.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_cmp_case_cstr_eq">ustr_cmp_case_cstr_eq()</a>
<br>Returns: Success or failure<br>Type: int 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[2]</strong>: A pointer to a constant C-style string<br>Type<strong>[2]</strong>: const char *
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works like comparing <a href="functions.html#ustr_cmp_case_cstr">ustr_cmp_case_cstr()</a> against 0.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_cmp_prefix_eq">ustr_cmp_prefix_eq()</a>
<br>Returns: Success or failure<br>Type: int 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[2]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[2]</strong>: const struct Ustr *
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works like comparing <a href="functions.html#ustr_cmp">ustr_cmp()</a> against 0, but the comparison
 is limited to the length of the right hand side.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_cmp_prefix_buf_eq">ustr_cmp_prefix_buf_eq()</a>
<br>Returns: Success or failure<br>Type: int 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[2]</strong>: A pointer to constant bytes, to compare<br>Type<strong>[2]</strong>: const void *
</td></tr><tr><td>Parameter<strong>[3]</strong>: Length of comparison bytes<br>Type<strong>[3]</strong>: size_t
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works like comparing <a href="functions.html#ustr_cmp_buf">ustr_cmp_buf()</a> against 0, but the
 comparison is limited to the length of the right hand side (Parameter[3]).


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_cmp_prefix_cstr_eq">ustr_cmp_prefix_cstr_eq()</a>
<br>Returns: Success or failure<br>Type: int 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[2]</strong>: A pointer to a constant C-style string<br>Type<strong>[2]</strong>: const char *
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works like comparing <a href="functions.html#ustr_cmp_cstr">ustr_cmp_cstr()</a> against 0, but the
 comparison is limited to the length of the right hand side.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_cmp_prefix_subustr_eq">ustr_cmp_prefix_subustr_eq()</a>
<br>Returns: Success or failure<br>Type: int 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[2]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[2]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[3]</strong>: Position in the Ustr<br>Type<strong>[3]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[4]</strong>: Length to compare from the Ustr<br>Type<strong>[4]</strong>: size_t
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works like comparing <a href="functions.html#ustr_cmp_subustr">ustr_cmp_subustr()</a> against 0, but the
 comparison is limited to the given length (Parameter[4]).


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_cmp_case_prefix_eq">ustr_cmp_case_prefix_eq()</a>
<br>Returns: Success or failure<br>Type: int 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[2]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[2]</strong>: const struct Ustr *
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works like comparing <a href="functions.html#ustr_cmp_case">ustr_cmp_case()</a> against 0, but the
 comparison is limited to the length of the right hand side.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_cmp_case_prefix_buf_eq">ustr_cmp_case_prefix_buf_eq()</a>
<br>Returns: Success or failure<br>Type: int 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[2]</strong>: A pointer to constant bytes, to compare<br>Type<strong>[2]</strong>: const void *
</td></tr><tr><td>Parameter<strong>[3]</strong>: Length of comparison bytes<br>Type<strong>[3]</strong>: size_t
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works like comparing <a href="functions.html#ustr_cmp_case_buf">ustr_cmp_case_buf()</a> against 0, but the
 comparison is limited to the length of the right hand side (Parameter[3]).


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_cmp_case_prefix_cstr_eq">ustr_cmp_case_prefix_cstr_eq()</a>
<br>Returns: Success or failure<br>Type: int 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[2]</strong>: A pointer to a constant C-style string<br>Type<strong>[2]</strong>: const char *
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works like comparing <a href="functions.html#ustr_cmp_case_cstr">ustr_cmp_case_cstr()</a> against 0, but the
 comparison is limited to the length of the right hand side.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_cmp_case_prefix_subustr_eq">ustr_cmp_case_prefix_subustr_eq()</a>
<br>Returns: Success or failure<br>Type: int 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[2]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[2]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[3]</strong>: Position in the Ustr<br>Type<strong>[3]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[4]</strong>: Length to compare from the Ustr<br>Type<strong>[4]</strong>: size_t
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works like comparing <a href="functions.html#ustr_cmp_case_subustr">ustr_cmp_case_subustr()</a> against 0, but the
 comparison is limited to the given length (Parameter[4]).


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_cmp_suffix_eq">ustr_cmp_suffix_eq()</a>
<br>Returns: Success or failure<br>Type: int 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[2]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[2]</strong>: const struct Ustr *
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works like <a href="functions.html#ustr_cmp_prefix_eq">ustr_cmp_prefix_eq()</a> but compares the end of the left
 hand side.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_cmp_suffix_buf_eq">ustr_cmp_suffix_buf_eq()</a>
<br>Returns: Success or failure<br>Type: int 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[2]</strong>: A pointer to constant bytes, to compare<br>Type<strong>[2]</strong>: const void *
</td></tr><tr><td>Parameter<strong>[3]</strong>: Length of comparison bytes<br>Type<strong>[3]</strong>: size_t
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works like <a href="functions.html#ustr_cmp_prefix_buf_eq">ustr_cmp_prefix_buf_eq()</a> but compares the end of
 the left hand side.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_cmp_suffix_cstr_eq">ustr_cmp_suffix_cstr_eq()</a>
<br>Returns: Success or failure<br>Type: int 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[2]</strong>: A pointer to a constant C-style string<br>Type<strong>[2]</strong>: const char *
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works like <a href="functions.html#ustr_cmp_prefix_cstr_eq">ustr_cmp_prefix_cstr_eq()</a> but compares the end of
 the left hand side.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_cmp_suffix_subustr_eq">ustr_cmp_suffix_subustr_eq()</a>
<br>Returns: Success or failure<br>Type: int 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[2]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[2]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[3]</strong>: Position in the Ustr<br>Type<strong>[3]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[4]</strong>: Length to compare from the Ustr<br>Type<strong>[4]</strong>: size_t
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works like comparing <a href="functions.html#ustr_cmp_subustr">ustr_cmp_subustr()</a> against 0, but
 compares the end of the left hand side.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_cmp_case_suffix_eq">ustr_cmp_case_suffix_eq()</a>
<br>Returns: Success or failure<br>Type: int 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[2]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[2]</strong>: const struct Ustr *
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works like <a href="functions.html#ustr_cmp_case_prefix_eq">ustr_cmp_case_prefix_eq()</a> but compares the end of
 the left hand side.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_cmp_case_suffix_buf_eq">ustr_cmp_case_suffix_buf_eq()</a>
<br>Returns: Success or failure<br>Type: int 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[2]</strong>: A pointer to constant bytes, to compare<br>Type<strong>[2]</strong>: const void *
</td></tr><tr><td>Parameter<strong>[3]</strong>: Length of comparison bytes<br>Type<strong>[3]</strong>: size_t
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works like <a href="functions.html#ustr_cmp_case_prefix_buf_eq">ustr_cmp_case_prefix_buf_eq()</a> but compares the end of
 the left hand side.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_cmp_case_suffix_cstr_eq">ustr_cmp_case_suffix_cstr_eq()</a>
<br>Returns: Success or failure<br>Type: int 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[2]</strong>: A pointer to a constant C-style string<br>Type<strong>[2]</strong>: const char *
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works like <a href="functions.html#ustr_cmp_case_prefix_cstr_eq">ustr_cmp_case_prefix_cstr_eq()</a> but compares the end
 of the left hand side.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_cmp_case_suffix_subustr_eq">ustr_cmp_case_suffix_subustr_eq()</a>
<br>Returns: Success or failure<br>Type: int 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[2]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[2]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[3]</strong>: Position in the Ustr<br>Type<strong>[3]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[4]</strong>: Length to compare from the Ustr<br>Type<strong>[4]</strong>: size_t
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works like comparing <a href="functions.html#ustr_cmp_case_subustr">ustr_cmp_case_subustr()</a> against 0, but
 compares the end of the left hand side.


</td></tr></table><table width="90%"><tr><td class="sect"><h2><a id="Searching%20for%20data%20in%20a%20Ustr">Searching for data in a Ustr</a></h2>
</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_srch_chr_fwd">ustr_srch_chr_fwd()</a>
<br>Returns: Position in the Ustr, or zero if not found<br>Type: size_t 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[2]</strong>: Offset within string to start searching at<br>Type<strong>[2]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[3]</strong>: Byte data to search for<br>Type<strong>[3]</strong>: char
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function searches for the data (Parameter[3]) in the Ustr, skipping an
 offset (Parameter[2]) number of bytes.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_srch_chr_rev">ustr_srch_chr_rev()</a>
<br>Returns: Position in the Ustr, or zero if not found<br>Type: size_t 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[2]</strong>: Offset within string to start searching at<br>Type<strong>[2]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[3]</strong>: Byte data to search for<br>Type<strong>[3]</strong>: char
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works like <a href="functions.html#ustr_srch_chr_fwd">ustr_srch_chr_fwd()</a> but it searches from the end of
 the string to the beginning.

</td></tr><tr><td><strong>Note:</strong></td></tr><tr><td><p>
</p><p>  The searching starts from the end of the string, and so the offset is the
 offset from the end. However the position of a byte is always relative to
 the begining, so to do a loop you need to take the position from the length.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_srch_buf_fwd">ustr_srch_buf_fwd()</a>
<br>Returns: Position in the Ustr, or zero if not found<br>Type: size_t 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[2]</strong>: Offset within string to start searching at<br>Type<strong>[2]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[3]</strong>: A pointer to data to search for<br>Type<strong>[3]</strong>: const void *
</td></tr><tr><td>Parameter<strong>[4]</strong>: Length of the data to search for<br>Type<strong>[4]</strong>: size_t
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function searches for the data (Parameter[3]) of length (Parameter[4])
 in the Ustr, skipping an offset (Parameter[2]) number of bytes.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_srch_buf_rev">ustr_srch_buf_rev()</a>
<br>Returns: Position in the Ustr, or zero if not found<br>Type: size_t 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[2]</strong>: Offset within string to start searching at<br>Type<strong>[2]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[3]</strong>: A pointer to data to search for<br>Type<strong>[3]</strong>: const void *
</td></tr><tr><td>Parameter<strong>[4]</strong>: Length of the data to search for<br>Type<strong>[4]</strong>: size_t
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works like <a href="functions.html#ustr_srch_buf_fwd">ustr_srch_buf_fwd()</a> but it searches from the end of
 the string to the beginning.

</td></tr><tr><td><strong>Note:</strong></td></tr><tr><td><p>
</p><p>  The searching starts from the end of the string, and so the offset is the
 offset from the end. However the position of a byte is always relative to
 the begining, so to do a loop you need to take the position from the length.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_srch_fwd">ustr_srch_fwd()</a>
<br>Returns: Position in the Ustr, or zero if not found<br>Type: size_t 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[2]</strong>: Offset within string to start searching at<br>Type<strong>[2]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[3]</strong>: A pointer to a constant <a href="design.html">Ustr string</a>, to search for<br>Type<strong>[3]</strong>: const struct Ustr *
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works like <a href="functions.html#ustr_srch_buf_fwd">ustr_srch_buf_fwd()</a> but it gets the data pointer by
 calling <a href="functions.html#ustr_cstr">ustr_cstr()</a> and the length by calling <a href="functions.html#ustr_len">ustr_len()</a> on the passed
 Ustr (Parameter[3]).


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_srch_rev">ustr_srch_rev()</a>
<br>Returns: Position in the Ustr, or zero if not found<br>Type: size_t 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[2]</strong>: Offset within string to start searching at<br>Type<strong>[2]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[3]</strong>: A pointer to a constant <a href="design.html">Ustr string</a>, to search for<br>Type<strong>[3]</strong>: const struct Ustr *
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works like <a href="functions.html#ustr_srch_fwd">ustr_srch_fwd()</a> but it searches from the end of
 the string to the beginning.

</td></tr><tr><td><strong>Note:</strong></td></tr><tr><td><p>
</p><p>  The searching starts from the end of the string, and so the offset is the
 offset from the end. However the position of a byte is always relative to
 the begining, so to do a loop you need to take the position from the length.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_srch_cstr_fwd">ustr_srch_cstr_fwd()</a>
<br>Returns: Position in the Ustr, or zero if not found<br>Type: size_t 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[2]</strong>: Offset within string to start searching at<br>Type<strong>[2]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[3]</strong>: A pointer to C-style string data, to search for<br>Type<strong>[3]</strong>: const char *
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works like <a href="functions.html#ustr_srch_buf_fwd">ustr_srch_buf_fwd()</a> but it gets the length by
 calling strlen() on the passed data (Parameter[3]).


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_srch_cstr_rev">ustr_srch_cstr_rev()</a>
<br>Returns: Position in the Ustr, or zero if not found<br>Type: size_t 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[2]</strong>: Offset within string to start searching at<br>Type<strong>[2]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[3]</strong>: A pointer to C-style string data, to search for<br>Type<strong>[3]</strong>: const char *
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works like <a href="functions.html#ustr_srch_cstr_fwd">ustr_srch_cstr_fwd()</a> but it searches from the end of
 the string to the beginning.

</td></tr><tr><td><strong>Note:</strong></td></tr><tr><td><p>
</p><p>  The searching starts from the end of the string, and so the offset is the
 offset from the end. However the position of a byte is always relative to
 the begining, so to do a loop you need to take the position from the length.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_srch_subustr_fwd">ustr_srch_subustr_fwd()</a>
<br>Returns: Position in the Ustr, or zero if not found<br>Type: size_t 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[2]</strong>: Offset within string to start searching at<br>Type<strong>[2]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[3]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[3]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[4]</strong>: Position in the Ustr<br>Type<strong>[4]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[5]</strong>: Length of data to search, from the Ustr<br>Type<strong>[5]</strong>: size_t
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works like <a href="functions.html#ustr_srch_fwd">ustr_srch_fwd()</a> but it moves the data to start at
 the correct position and limits the length to the value specified.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_srch_subustr_rev">ustr_srch_subustr_rev()</a>
<br>Returns: Position in the Ustr, or zero if not found<br>Type: size_t 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[2]</strong>: Offset within string to start searching at<br>Type<strong>[2]</strong>:  size_t
</td></tr><tr><td>Parameter<strong>[3]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[3]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[4]</strong>: Position in the Ustr<br>Type<strong>[4]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[5]</strong>: Length of data to search, from the Ustr<br>Type<strong>[5]</strong>: size_t
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works like <a href="functions.html#ustr_srch_rev">ustr_srch_rev()</a> but it moves the data to start at
 the correct position and limits the length to the value specified.

</td></tr><tr><td><strong>Note:</strong></td></tr><tr><td><p>
</p><p>  The searching starts from the end of the string, and so the offset is the
 offset from the end. However the position of a byte is always relative to
 the begining, so to do a loop you need to take the position from the length.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_srch_case_chr_fwd">ustr_srch_case_chr_fwd()</a>
<br>Returns: Position in the Ustr, or zero if not found<br>Type: size_t 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[2]</strong>: Offset within string to start searching at<br>Type<strong>[2]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[3]</strong>: Byte data to search for<br>Type<strong>[3]</strong>: char
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works like <a href="functions.html#ustr_srch_chr_fwd">ustr_srch_chr_fwd()</a>, but treats ASCII uppercase
 and lowercase as equivalent.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_srch_case_chr_rev">ustr_srch_case_chr_rev()</a>
<br>Returns: Position in the Ustr, or zero if not found<br>Type: size_t 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[2]</strong>: Offset within string to start searching at<br>Type<strong>[2]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[3]</strong>: Byte data to search for<br>Type<strong>[3]</strong>: char
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works like <a href="functions.html#ustr_srch_chr_fwd">ustr_srch_chr_fwd()</a>, but treats ASCII uppercase
 and lowercase as equivalent.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_srch_case_buf_fwd">ustr_srch_case_buf_fwd()</a>
<br>Returns: Position in the Ustr, or zero if not found<br>Type: size_t 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[2]</strong>: Offset within string to start searching at<br>Type<strong>[2]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[3]</strong>: A pointer to data to search for<br>Type<strong>[3]</strong>: const void *
</td></tr><tr><td>Parameter<strong>[4]</strong>: Length of the data to search for<br>Type<strong>[4]</strong>: size_t
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works like <a href="functions.html#ustr_srch_buf_fwd">ustr_srch_buf_fwd()</a>, but treats ASCII uppercase and
 lowercase as equivalent.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_srch_case_buf_rev">ustr_srch_case_buf_rev()</a>
<br>Returns: Position in the Ustr, or zero if not found<br>Type: size_t 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[2]</strong>: Offset within string to start searching at<br>Type<strong>[2]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[3]</strong>: A pointer to data to search for<br>Type<strong>[3]</strong>: const void *
</td></tr><tr><td>Parameter<strong>[4]</strong>: Length of the data to search for<br>Type<strong>[4]</strong>: size_t
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works like <a href="functions.html#ustr_srch_buf_rev">ustr_srch_buf_rev()</a>, but treats ASCII uppercase and
 lowercase as equivalent.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_srch_case_fwd">ustr_srch_case_fwd()</a>
<br>Returns: Position in the Ustr, or zero if not found<br>Type: size_t 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[2]</strong>: Offset within string to start searching at<br>Type<strong>[2]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[3]</strong>: A pointer to a constant <a href="design.html">Ustr string</a>, to search for<br>Type<strong>[3]</strong>: const struct Ustr *
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works like <a href="functions.html#ustr_srch_fwd">ustr_srch_fwd()</a>, but treats ASCII uppercase and
 lowercase as equivalent.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_srch_case_rev">ustr_srch_case_rev()</a>
<br>Returns: Position in the Ustr, or zero if not found<br>Type: size_t 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[2]</strong>: Offset within string to start searching at<br>Type<strong>[2]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[3]</strong>: A pointer to a constant <a href="design.html">Ustr string</a>, to search for<br>Type<strong>[3]</strong>: const struct Ustr *
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works like <a href="functions.html#ustr_srch_rev">ustr_srch_rev()</a>, but treats ASCII uppercase and
 lowercase as equivalent.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_srch_case_cstr_fwd">ustr_srch_case_cstr_fwd()</a>
<br>Returns: Position in the Ustr, or zero if not found<br>Type: size_t 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[2]</strong>: Offset within string to start searching at<br>Type<strong>[2]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[3]</strong>: A pointer to C-style string data, to search for<br>Type<strong>[3]</strong>: const char *
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works like <a href="functions.html#ustr_srch_cstr_fwd">ustr_srch_cstr_fwd()</a>, but treats ASCII uppercase
 and lowercase as equivalent.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_srch_case_cstr_rev">ustr_srch_case_cstr_rev()</a>
<br>Returns: Position in the Ustr, or zero if not found<br>Type: size_t 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[2]</strong>: Offset within string to start searching at<br>Type<strong>[2]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[3]</strong>: A pointer to C-style string data, to search for<br>Type<strong>[3]</strong>: const char *
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works like <a href="functions.html#ustr_srch_cstr_rev">ustr_srch_cstr_rev()</a>, but treats ASCII uppercase
 and lowercase as equivalent.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_srch_case_subustr_fwd">ustr_srch_case_subustr_fwd()</a>
<br>Returns: Position in the Ustr, or zero if not found<br>Type: size_t 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[2]</strong>: Offset within string to start searching at<br>Type<strong>[2]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[3]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[3]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[4]</strong>: Position in the Ustr<br>Type<strong>[4]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[5]</strong>: Length of data to search, from the Ustr<br>Type<strong>[5]</strong>: size_t
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works like <a href="functions.html#ustr_srch_subustr_fwd">ustr_srch_subustr_fwd()</a>, but treats ASCII uppercase
 and lowercase as equivalent.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_srch_case_subustr_rev">ustr_srch_case_subustr_rev()</a>
<br>Returns: Position in the Ustr, or zero if not found<br>Type: size_t 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[2]</strong>: Offset within string to start searching at<br>Type<strong>[2]</strong>:  size_t
</td></tr><tr><td>Parameter<strong>[3]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[3]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[4]</strong>: Position in the Ustr<br>Type<strong>[4]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[5]</strong>: Length of data to search, from the Ustr<br>Type<strong>[5]</strong>: size_t
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works like <a href="functions.html#ustr_srch_subustr_rev">ustr_srch_subustr_rev()</a>, but treats ASCII uppercase
 and lowercase as equivalent.


</td></tr></table><table width="90%"><tr><td class="sect"><h2><a id="Span%20lengths%20of%20data%20in%20a%20Ustr">Span lengths of data in a Ustr</a></h2>
</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_spn_chr_fwd">ustr_spn_chr_fwd()</a>
<br>Returns: Number of bytes in the span<br>Type: size_t 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[2]</strong>: Offset within string, to start spanning from<br>Type<strong>[2]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[3]</strong>: Byte data<br>Type<strong>[3]</strong>: char
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function returns the length of the start of the Ustr (Parameter[1]) that
 only contains bytes that are equal to the data (Parameter[3]), skipping
 offset (Parameter[2]) bytes.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_spn_chr_rev">ustr_spn_chr_rev()</a>
<br>Returns: Number of bytes in the span<br>Type: size_t 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[2]</strong>: Offset within string, to start spanning from<br>Type<strong>[2]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[3]</strong>: Byte data<br>Type<strong>[3]</strong>: char
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function returns the length of the end of the Ustr (Parameter[1]) that
 only contains bytes that are equal to the data (Parameter[3]), skipping
 offset (Parameter[2]) bytes.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_spn_chrs_fwd">ustr_spn_chrs_fwd()</a>
<br>Returns: Number of bytes in the span<br>Type: size_t 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[2]</strong>: Offset within string, to start spanning from<br>Type<strong>[2]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[3]</strong>: Array of byte data, for spanning<br>Type<strong>[3]</strong>: const char *
</td></tr><tr><td>Parameter<strong>[4]</strong>: Length of byte data, for spanning<br>Type<strong>[4]</strong>: size_t
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function returns the length of the start of the Ustr (Parameter[1]) that
 only contains bytes that are equal to any byte in the data (Parameter[3]),
 skipping offset (Parameter[2]) bytes.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_spn_chrs_rev">ustr_spn_chrs_rev()</a>
<br>Returns: Number of bytes in the span<br>Type: size_t 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[2]</strong>: Offset within string, to start spanning from<br>Type<strong>[2]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[3]</strong>: Array of byte data<br>Type<strong>[3]</strong>: const char *
</td></tr><tr><td>Parameter<strong>[4]</strong>: Length of byte data<br>Type<strong>[4]</strong>: size_t
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function returns the length of the end of the Ustr (Parameter[1]) that
 only contains bytes that are equal to any byte in the data (Parameter[3]),
 skipping offset (Parameter[2]) bytes.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_spn_fwd">ustr_spn_fwd()</a>
<br>Returns: Number of bytes in the span<br>Type: size_t 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[2]</strong>: Offset within string, to start spanning from<br>Type<strong>[2]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[3]</strong>: A pointer to a constant <a href="design.html">Ustr string</a>, containing spanning bytes<br>Type<strong>[3]</strong>: const struct Ustr *
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works like <a href="functions.html#ustr_spn_buf_fwd">ustr_spn_buf_fwd()</a> but passing <a href="functions.html#ustr_cstr">ustr_cstr()</a> and
 <a href="functions.html#ustr_len">ustr_len()</a>


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_spn_rev">ustr_spn_rev()</a>
<br>Returns: Number of bytes in the span<br>Type: size_t 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[2]</strong>: Offset within string, to start spanning from<br>Type<strong>[2]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[3]</strong>: A pointer to a constant <a href="design.html">Ustr string</a>, containing spanning bytes<br>Type<strong>[3]</strong>: const struct Ustr *
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works like <a href="functions.html#ustr_spn_buf_rev">ustr_spn_buf_rev()</a> but passing <a href="functions.html#ustr_cstr">ustr_cstr()</a> and
 <a href="functions.html#ustr_len">ustr_len()</a>


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_spn_cstr_fwd">ustr_spn_cstr_fwd()</a>
<br>Returns: Number of bytes in the span<br>Type: size_t 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[2]</strong>: Offset within string, to start spanning from<br>Type<strong>[2]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[3]</strong>: A pointer to a constant C-style string, containing spanning bytes<br>Type<strong>[3]</strong>: const char *
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works like <a href="functions.html#ustr_spn_buf_fwd">ustr_spn_buf_fwd()</a> but passing strlen() for the
 length.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_spn_cstr_rev">ustr_spn_cstr_rev()</a>
<br>Returns: Number of bytes in the span<br>Type: size_t 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[2]</strong>: Offset within string, to start spanning from<br>Type<strong>[2]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[3]</strong>: A pointer to a constant C-style string, containing spanning bytes<br>Type<strong>[3]</strong>: const char *
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works like <a href="functions.html#ustr_spn_buf_rev">ustr_spn_buf_rev()</a> but passing strlen() for the
 length.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_cspn_chr_fwd">ustr_cspn_chr_fwd()</a>
<br>Returns: Number of bytes not in the span<br>Type: size_t 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[2]</strong>: Offset within string, to start compliment spanning from<br>Type<strong>[2]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[3]</strong>: Byte data<br>Type<strong>[3]</strong>: char
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function returns the length of the start of the Ustr (Parameter[1]) that
 only contains bytes that are not equal to the data (Parameter[3]), skipping
 offset (Parameter[2]) bytes.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_cspn_chr_rev">ustr_cspn_chr_rev()</a>
<br>Returns: Number of bytes not in the span<br>Type: size_t 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[2]</strong>: Offset within string, to start compliment spanning from<br>Type<strong>[2]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[3]</strong>: Byte data<br>Type<strong>[3]</strong>: char
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function returns the length of the end of the Ustr (Parameter[1]) that
 only contains bytes that are not equal to the data (Parameter[3]), skipping
 offset (Parameter[2]) bytes.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_cspn_chrs_fwd">ustr_cspn_chrs_fwd()</a>
<br>Returns: Number of bytes not in the span<br>Type: size_t 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[2]</strong>: Offset within string, to start compliment spanning from<br>Type<strong>[2]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[3]</strong>: Array of byte data<br>Type<strong>[3]</strong>: const char *
</td></tr><tr><td>Parameter<strong>[4]</strong>: Length of byte data<br>Type<strong>[4]</strong>: size_t
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function returns the length of the start of the Ustr (Parameter[1]) that
 only contains bytes that are not equal to any byte in the data (Parameter[3]),
 skipping offset (Parameter[2]) bytes.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_cspn_chrs_rev">ustr_cspn_chrs_rev()</a>
<br>Returns: Number of bytes not in the span<br>Type: size_t 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[2]</strong>: Offset within string, to start compliment spanning from<br>Type<strong>[2]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[3]</strong>: Array of byte data<br>Type<strong>[3]</strong>: const char *
</td></tr><tr><td>Parameter<strong>[4]</strong>: Length of byte data<br>Type<strong>[4]</strong>: size_t
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function returns the length of the end of the Ustr (Parameter[1]) that
 only contains bytes that are not equal to any byte in the data (Parameter[3]),
 skipping offset (Parameter[2]) bytes.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_cspn_fwd">ustr_cspn_fwd()</a>
<br>Returns: Number of bytes not in the span<br>Type: size_t 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[2]</strong>: Offset within string, to start compliment spanning from<br>Type<strong>[2]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[3]</strong>: A pointer to a constant <a href="design.html">Ustr string</a>, containing spanning bytes<br>Type<strong>[3]</strong>: const struct Ustr *
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works like <a href="functions.html#ustr_cspn_buf_fwd">ustr_cspn_buf_fwd()</a> but passing <a href="functions.html#ustr_cstr">ustr_cstr()</a> and
 <a href="functions.html#ustr_len">ustr_len()</a>


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_cspn_rev">ustr_cspn_rev()</a>
<br>Returns: Number of bytes not in the span<br>Type: size_t 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[2]</strong>: Offset within string, to start compliment spanning from<br>Type<strong>[2]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[3]</strong>: A pointer to a constant <a href="design.html">Ustr string</a>, containing spanning bytes<br>Type<strong>[3]</strong>: const struct Ustr *
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works like <a href="functions.html#ustr_cspn_buf_rev">ustr_cspn_buf_rev()</a> but passing <a href="functions.html#ustr_cstr">ustr_cstr()</a> and
 <a href="functions.html#ustr_len">ustr_len()</a>


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_cspn_cstr_fwd">ustr_cspn_cstr_fwd()</a>
<br>Returns: Number of bytes not in the span<br>Type: size_t 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[2]</strong>: Offset within string, to start compliment spanning from<br>Type<strong>[2]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[3]</strong>: A pointer to a constant C-style string, containing spanning bytes<br>Type<strong>[3]</strong>: const char *
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works like <a href="functions.html#ustr_cspn_buf_fwd">ustr_cspn_buf_fwd()</a> but passing strlen() for the
 length.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_cspn_cstr_rev">ustr_cspn_cstr_rev()</a>
<br>Returns: Number of bytes not in the span<br>Type: size_t 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[2]</strong>: Offset within string, to start spanning from<br>Type<strong>[2]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[3]</strong>: A pointer to a constant C-style string, containing spanning bytes<br>Type<strong>[3]</strong>: const char *
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works like <a href="functions.html#ustr_cspn_buf_rev">ustr_cspn_buf_rev()</a> but passing strlen() for the
 length.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_utf8_spn_chrs_fwd">ustr_utf8_spn_chrs_fwd()</a>
<br>Returns: Number of UTF-8 characters not in the span<br>Type: size_t 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a constant Ustr UTF-8 string<br>Type<strong>[1]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[2]</strong>: Offset within string, in UTF-8 characters, to start spanning from<br>Type<strong>[2]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[3]</strong>: A pointer to a constant C-style UTF-8 string<br>Type<strong>[3]</strong>: const char *
</td></tr><tr><td>Parameter<strong>[4]</strong>: Length of the C-style UTF-8 string<br>Type<strong>[4]</strong>: size_t
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works like <a href="functions.html#ustr_spn_chrs_fwd">ustr_spn_chrs_fwd()</a> but the return value, offset, and
 length all use UTF-8 characters and not bytes.

</td></tr><tr><td><strong>Note:</strong></td></tr><tr><td><p>
</p><p>  This is much slower than <a href="functions.html#ustr_spn_chrs_fwd">ustr_spn_chrs_fwd()</a> but given &quot;xy&quot; as a multi-byte
 UTF-8 character it understands that the span over "xyxz" is 1 UTF-8 character
 and not 3 bytes.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_utf8_spn_chrs_rev">ustr_utf8_spn_chrs_rev()</a>
<br>Returns: Number of UTF-8 characters not in the span<br>Type: size_t 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a constant Ustr UTF-8 string<br>Type<strong>[1]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[2]</strong>: Offset within string, in UTF-8 characters, to start spanning from<br>Type<strong>[2]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[3]</strong>: A pointer to a constant C-style UTF-8 string<br>Type<strong>[3]</strong>: const char *
</td></tr><tr><td>Parameter<strong>[4]</strong>: <br>Type<strong>[4]</strong>: size_t
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works like <a href="functions.html#ustr_spn_chrs_rev">ustr_spn_chrs_rev()</a> but the return value, offset, and
 length all use UTF-8 characters and not bytes.

</td></tr><tr><td><strong>Note:</strong></td></tr><tr><td><p>
</p><p>  This is much slower than <a href="functions.html#ustr_spn_chrs_rev">ustr_spn_chrs_rev()</a> but given &quot;xy&quot; as a multi-byte
 UTF-8 character it understands that the span over "xyxz" is 1 UTF-8 character
 and not 3 bytes.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_utf8_spn_fwd">ustr_utf8_spn_fwd()</a>
<br>Returns: Number of UTF-8 characters not in the span<br>Type: size_t 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a constant Ustr UTF-8 string<br>Type<strong>[1]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[2]</strong>: Offset within string, in UTF-8 characters, to start spanning from<br>Type<strong>[2]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[3]</strong>: A pointer to a constant Ustr UTF-8 string<br>Type<strong>[3]</strong>: const struct Ustr *
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works like <a href="functions.html#ustr_spn_fwd">ustr_spn_fwd()</a> but the return value, offset, and
 length all use UTF-8 characters and not bytes.

</td></tr><tr><td><strong>Note:</strong></td></tr><tr><td><p>
</p><p>  This is much slower than <a href="functions.html#ustr_spn_fwd">ustr_spn_fwd()</a> but given &quot;xy&quot; as a multi-byte
 UTF-8 character it understands that the span over "xyxz" is 1 UTF-8 character
 and not 3 bytes.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_utf8_spn_rev">ustr_utf8_spn_rev()</a>
<br>Returns: Number of UTF-8 characters not in the span<br>Type: size_t 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a constant Ustr UTF-8 string<br>Type<strong>[1]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[2]</strong>: Offset within string, in UTF-8 characters, to start spanning from<br>Type<strong>[2]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[3]</strong>: A pointer to a constant Ustr UTF-8 string<br>Type<strong>[3]</strong>: const struct Ustr *
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works like <a href="functions.html#ustr_spn_rev">ustr_spn_rev()</a> but the return value, offset, and
 length all use UTF-8 characters and not bytes.

</td></tr><tr><td><strong>Note:</strong></td></tr><tr><td><p>
</p><p>  This is much slower than <a href="functions.html#ustr_spn_rev">ustr_spn_rev()</a> but given &quot;xy&quot; as a multi-byte
 UTF-8 character it understands that the span over "xyxz" is 1 UTF-8 character
 and not 3 bytes.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_utf8_spn_cstr_fwd">ustr_utf8_spn_cstr_fwd()</a>
<br>Returns: Number of UTF-8 characters not in the span<br>Type: size_t 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a constant Ustr UTF-8 string<br>Type<strong>[1]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[2]</strong>: Offset within string, in UTF-8 characters, to start spanning from<br>Type<strong>[2]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[3]</strong>: A pointer to a constant C-style UTF-8 string<br>Type<strong>[3]</strong>: const char *
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works like <a href="functions.html#ustr_spn_cstr_fwd">ustr_spn_cstr_fwd()</a> but the return value, offset, and
 length all use UTF-8 characters and not bytes.

</td></tr><tr><td><strong>Note:</strong></td></tr><tr><td><p>
</p><p>  This is much slower than <a href="functions.html#ustr_spn_cstr_fwd">ustr_spn_cstr_fwd()</a> but given &quot;xy&quot; as a multi-byte
 UTF-8 character it understands that the span over "xyxz" is 1 UTF-8 character
 and not 3 bytes.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_utf8_spn_cstr_rev">ustr_utf8_spn_cstr_rev()</a>
<br>Returns: Number of UTF-8 characters not in the span<br>Type: size_t 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a constant Ustr UTF-8 string<br>Type<strong>[1]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[2]</strong>: Offset within string, in UTF-8 characters, to start spanning from<br>Type<strong>[2]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[3]</strong>: A pointer to a constant C-style UTF-8 string<br>Type<strong>[3]</strong>: const char *
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works like <a href="functions.html#ustr_spn_cstr_rev">ustr_spn_cstr_rev()</a> but the return value, offset, and
 length all use UTF-8 characters and not bytes.

</td></tr><tr><td><strong>Note:</strong></td></tr><tr><td><p>
</p><p>  This is much slower than <a href="functions.html#ustr_spn_cstr_rev">ustr_spn_cstr_rev()</a> but given &quot;xy&quot; as a multi-byte
 UTF-8 character it understands that the span over "xyxz" is 1 UTF-8 character
 and not 3 bytes.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_utf8_cspn_chrs_fwd">ustr_utf8_cspn_chrs_fwd()</a>
<br>Returns: Number of UTF-8 characters not in the span<br>Type: size_t 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a constant Ustr UTF-8 string<br>Type<strong>[1]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[2]</strong>: Offset within string, in UTF-8 characters, to start compliment spanning from<br>Type<strong>[2]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[3]</strong>: A pointer to a constant C-style UTF-8 string<br>Type<strong>[3]</strong>: const char *
</td></tr><tr><td>Parameter<strong>[4]</strong>: Length of the C-style UTF-8 string<br>Type<strong>[4]</strong>: size_t
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works like <a href="functions.html#ustr_cspn_chrs_fwd">ustr_cspn_chrs_fwd()</a> but the return value, offset,
 and length all use UTF-8 characters and not bytes.

</td></tr><tr><td><strong>Note:</strong></td></tr><tr><td><p>
</p><p>  This is much slower than <a href="functions.html#ustr_cspn_chrs_fwd">ustr_cspn_chrs_fwd()</a> but given &quot;xy&quot; as a multi-byte
 UTF-8 character it understands that the compliment span over "xzxy" is 1 UTF-8
 character and not 0 bytes.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_utf8_cspn_chrs_rev">ustr_utf8_cspn_chrs_rev()</a>
<br>Returns: Number of UTF-8 characters not in the span<br>Type: size_t 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a constant Ustr UTF-8 string<br>Type<strong>[1]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[2]</strong>: Offset within string, in UTF-8 characters, to start compliment spanning from<br>Type<strong>[2]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[3]</strong>: A pointer to a constant C-style UTF-8 string<br>Type<strong>[3]</strong>: const char *
</td></tr><tr><td>Parameter<strong>[4]</strong>: Length of the C-style UTF-8 string<br>Type<strong>[4]</strong>: size_t
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works like <a href="functions.html#ustr_cspn_chrs_rev">ustr_cspn_chrs_rev()</a> but the return value, offset,
 and length all use UTF-8 characters and not bytes.

</td></tr><tr><td><strong>Note:</strong></td></tr><tr><td><p>
</p><p>  This is much slower than <a href="functions.html#ustr_cspn_chrs_rev">ustr_cspn_chrs_rev()</a> but given &quot;xy&quot; as a multi-byte
 UTF-8 character it understands that the compliment span over "xzxy" is 1 UTF-8
 character and not 0 bytes.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_utf8_cspn_fwd">ustr_utf8_cspn_fwd()</a>
<br>Returns: Number of UTF-8 characters not in the span<br>Type: size_t 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a constant Ustr UTF-8 string<br>Type<strong>[1]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[2]</strong>: Offset within string, in UTF-8 characters, to start compliment spanning from<br>Type<strong>[2]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[3]</strong>: A pointer to a constant Ustr UTF-8 string, containing spanning data<br>Type<strong>[3]</strong>: const struct Ustr *
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works like <a href="functions.html#ustr_cspn_fwd">ustr_cspn_fwd()</a> but the return value, offset,
 and length all use UTF-8 characters and not bytes.

</td></tr><tr><td><strong>Note:</strong></td></tr><tr><td><p>
</p><p>  This is much slower than <a href="functions.html#ustr_cspn_fwd">ustr_cspn_fwd()</a> but given &quot;xy&quot; as a multi-byte
 UTF-8 character it understands that the compliment span over "xzxy" is 1 UTF-8
 character and not 0 bytes.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_utf8_cspn_rev">ustr_utf8_cspn_rev()</a>
<br>Returns: Number of UTF-8 characters not in the span<br>Type: size_t 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a constant Ustr UTF-8 string<br>Type<strong>[1]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[2]</strong>: Offset within string, in UTF-8 characters, to start compliment spanning from<br>Type<strong>[2]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[3]</strong>: A pointer to constant Ustr UTF-8 string data, containing spanning data<br>Type<strong>[3]</strong>: const struct Ustr *
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works like <a href="functions.html#ustr_cspn_rev">ustr_cspn_rev()</a> but the return value, offset,
 and length all use UTF-8 characters and not bytes.

</td></tr><tr><td><strong>Note:</strong></td></tr><tr><td><p>
</p><p>  This is much slower than <a href="functions.html#ustr_cspn_rev">ustr_cspn_rev()</a> but given &quot;xy&quot; as a multi-byte
 UTF-8 character it understands that the compliment span over "xzxy" is 1 UTF-8
 character and not 0 bytes.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_utf8_cspn_cstr_fwd">ustr_utf8_cspn_cstr_fwd()</a>
<br>Returns: Number of UTF-8 characters not in the span<br>Type: size_t 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a constant Ustr UTF-8 string<br>Type<strong>[1]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[2]</strong>: Offset within string, in UTF-8 characters, to start compliment spanning from<br>Type<strong>[2]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[3]</strong>: A pointer to constant C-style UTF-8 string data, containing spanning data<br>Type<strong>[3]</strong>: const char *
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works like <a href="functions.html#ustr_cspn_cstr_fwd">ustr_cspn_cstr_fwd()</a> but the return value, offset,
 and length all use UTF-8 characters and not bytes.

</td></tr><tr><td><strong>Note:</strong></td></tr><tr><td><p>
</p><p>  This is much slower than <a href="functions.html#ustr_cspn_cstr_fwd">ustr_cspn_cstr_fwd()</a> but given &quot;xy&quot; as a multi-byte
 UTF-8 character it understands that the compliment span over "xzxy" is 1 UTF-8
 character and not 0 bytes.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_utf8_cspn_cstr_rev">ustr_utf8_cspn_cstr_rev()</a>
<br>Returns: Number of UTF-8 characters not in the span<br>Type: size_t 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a constant Ustr UTF-8 string<br>Type<strong>[1]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[2]</strong>: Offset within string, in UTF-8 characters, to start compliment spanning from<br>Type<strong>[2]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[3]</strong>: A pointer to C-style UTF-8 string data, containing spanning data<br>Type<strong>[3]</strong>: const char *
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works like <a href="functions.html#ustr_cspn_cstr_rev">ustr_cspn_cstr_rev()</a> but the return value, offset,
 and length all use UTF-8 characters and not bytes.

</td></tr><tr><td><strong>Note:</strong></td></tr><tr><td><p>
</p><p>  This is much slower than <a href="functions.html#ustr_spn_cstr_rev">ustr_spn_cstr_rev()</a> but given &quot;xy&quot; as a multi-byte
 UTF-8 character it understands that the compliment span over "xzxy" is 1 UTF-8
 character and not 0 bytes.


</td></tr></table><table width="90%"><tr><td class="sect"><h2><a id="Doing%20IO%20from%20or%20to%20a%20Ustr">Doing IO from or to a Ustr</a></h2>
</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_io_get">ustr_io_get()</a>
<br>Returns: Success or failure<br>Type: int 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a pointer to a <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: struct Ustr **
</td></tr><tr><td>Parameter<strong>[2]</strong>: A pointer to a C file object<br>Type<strong>[2]</strong>: FILE *
</td></tr><tr><td>Parameter<strong>[3]</strong>: Number of bytes to read<br>Type<strong>[3]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[4]</strong>: Returned number of bytes read<br>Type<strong>[4]</strong>: size_t *
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function tries to read a minimum number of bytes from the file object,
 into the <a href="design.html">Ustr string</a>. The exact number read is returned, unless (Parameter[4])
 is NULL.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_io_getfile">ustr_io_getfile()</a>
<br>Returns: Success or failure<br>Type: int 
</td></tr><tr><td>Parameter<strong>[1]</strong>: Pointer to a pointer to a <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: struct Ustr **
</td></tr><tr><td>Parameter<strong>[2]</strong>: A pointer to a C file object<br>Type<strong>[2]</strong>: FILE *
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function calls <a href="functions.html#ustr_io_get">ustr_io_get()</a> rpeatedly until EOF is encountered.

</td></tr><tr><td><strong>Note:</strong></td></tr><tr><td><p>
</p><p>  The errno value when this function ends could either be from fopen(),
 fread(), or if both of the those succeeded from fclose().


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_io_getfilename">ustr_io_getfilename()</a>
<br>Returns: Success or failure<br>Type: int 
</td></tr><tr><td>Parameter<strong>[1]</strong>: Pointer to a pointer to a <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: struct Ustr **
</td></tr><tr><td>Parameter<strong>[2]</strong>: A C-style string of a filename<br>Type<strong>[2]</strong>: const char *
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function opens a specified file, and then calls <a href="functions.html#ustr_io_getfile">ustr_io_getfile()</a>.
 Finally closing the FILE * object.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_io_getdelim">ustr_io_getdelim()</a>
<br>Returns: Success or failure<br>Type: int 
</td></tr><tr><td>Parameter<strong>[1]</strong>: Pointer to a pointer to a <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: struct Ustr **
</td></tr><tr><td>Parameter<strong>[2]</strong>: A pointer to a C file object<br>Type<strong>[2]</strong>: FILE *
</td></tr><tr><td>Parameter<strong>[3]</strong>: A delimiter byte to stop reading at<br>Type<strong>[3]</strong>: char
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function reads bytes from the file until it hits the delimiter byte.

</td></tr><tr><td><strong>Note:</strong></td></tr><tr><td><p>
</p><p>  The delimiter is included, use <a href="functions.html#ustr_del">ustr_del()</a> to remove 1 byte from the end if you
 don't want it.
</p><p>  This function assumes a delimiter will happen every 80 bytes or so.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_io_getline">ustr_io_getline()</a>
<br>Returns: Success or failure<br>Type: int 
</td></tr><tr><td>Parameter<strong>[1]</strong>: Pointer to a pointer to a <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: struct Ustr **
</td></tr><tr><td>Parameter<strong>[2]</strong>: A pointer to a C file object<br>Type<strong>[2]</strong>: FILE *
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works like calling <a href="functions.html#ustr_io_getdelim">ustr_io_getdelim()</a> with '\n' as the
 delimiter.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_io_put">ustr_io_put()</a>
<br>Returns: Success or failure<br>Type: int
</td></tr><tr><td>Parameter<strong>[1]</strong>: Pointer to a pointer to a <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: struct Ustr **
</td></tr><tr><td>Parameter<strong>[2]</strong>: A pointer to a C file object<br>Type<strong>[2]</strong>: FILE *
</td></tr><tr><td>Parameter<strong>[3]</strong>: Number of bytes to write<br>Type<strong>[3]</strong>: size_t
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function is the opposite of <a href="functions.html#ustr_io_get">ustr_io_get()</a>, taking bytes from the
 beginning of the Ustr and writting them to the file.

</td></tr><tr><td><strong>Note:</strong></td></tr><tr><td><p>
</p><p>  Deleting bytes from the begining of a <a href="design.html">Ustr string</a> is the most inefficient
 thing to do, so it is recommended to use <a href="functions.html#ustr_io_putfile">ustr_io_putfile()</a>.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_io_putline">ustr_io_putline()</a>
<br>Returns: Success or failure<br>Type: int 
</td></tr><tr><td>Parameter<strong>[1]</strong>: Pointer to a pointer to a <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: struct Ustr **
</td></tr><tr><td>Parameter<strong>[2]</strong>: A pointer to a C file object<br>Type<strong>[2]</strong>: FILE *
</td></tr><tr><td>Parameter<strong>[3]</strong>: Number of bytes to write<br>Type<strong>[3]</strong>: size_t
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works like calling <a href="functions.html#ustr_io_put">ustr_io_put()</a>, and then writting a '\n' to
 the file.

</td></tr><tr><td><strong>Note:</strong></td></tr><tr><td><p>
</p><p>  This doesn't write a line from the Ustr to the file, if you want that call
 <a href="functions.html#ustr_io_put">ustr_io_put()</a> directly, using the return from <a href="functions.html#ustr_srch_chr_fwd">ustr_srch_chr_fwd()</a> (with a '\n')
 as the number of bytes argument.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_io_putfile">ustr_io_putfile()</a>
<br>Returns: Success or failure<br>Type: int 
</td></tr><tr><td>Parameter<strong>[1]</strong>: Pointer to a pointer to a <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: struct Ustr **
</td></tr><tr><td>Parameter<strong>[2]</strong>: A pointer to a C file object<br>Type<strong>[2]</strong>: FILE *
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works like calling <a href="functions.html#ustr_io_put">ustr_io_put()</a> with <a href="functions.html#ustr_len">ustr_len()</a> as the number
 of bytes.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_io_putfileline">ustr_io_putfileline()</a>
<br>Returns: Success or failure<br>Type: int 
</td></tr><tr><td>Parameter<strong>[1]</strong>: Pointer to a pointer to a <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: struct Ustr **
</td></tr><tr><td>Parameter<strong>[2]</strong>: A pointer to a C file object<br>Type<strong>[2]</strong>: FILE *
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works like calling <a href="functions.html#ustr_io_putline">ustr_io_putline()</a> with <a href="functions.html#ustr_len">ustr_len()</a> as the
 number of bytes.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_io_putfilename">ustr_io_putfilename()</a>
<br>Returns: Success or failure<br>Type: int 
</td></tr><tr><td>Parameter<strong>[1]</strong>: Pointer to a pointer to a <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: struct Ustr **
</td></tr><tr><td>Parameter<strong>[2]</strong>: A C-style string of a filename<br>Type<strong>[2]</strong>: const char *
</td></tr><tr><td>Parameter<strong>[3]</strong>: A C-style string of a filemode (the second argument to fopen)<br>Type<strong>[3]</strong>: const char *
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function opens a specified file, and then calls <a href="functions.html#ustr_io_putfile">ustr_io_putfile()</a>.
 Finally closing the FILE * object.

</td></tr><tr><td><strong>Note:</strong></td></tr><tr><td><p>
</p><p>  The errno value when this function ends could either be from fopen(),
 fwrite(), or if both of the those succeeded from fclose().


</td></tr></table><table width="90%"><tr><td class="sect"><h2><a id="String%20substitution%2freplacement">String substitution/replacement</a></h2>
</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_sub_undef">ustr_sub_undef()</a>
<br>Returns: Success or failure<br>Type: int 
</td></tr><tr><td>Parameter<strong>[1]</strong>: Pointer to a pointer to a Ustr<br>Type<strong>[1]</strong>: struct Ustr **
</td></tr><tr><td>Parameter<strong>[2]</strong>: Position where to start substitution<br>Type<strong>[2]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[3]</strong>: Length of undefined data<br>Type<strong>[3]</strong>: size_t
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  The <a href="design.html">Ustr string</a> is expanded as required (possibly reallocated) so that it can
 contain length (Parameter[2]) data, from the required position. If the length
 is not zero the Ustr will be writable. Or it'll return <a href="constants.html#USTR_FALSE">USTR_FALSE</a> (zero) on
 failure.

</td></tr><tr><td><strong>Note:</strong></td></tr><tr><td><p>
</p><p>  You can think of the operation as two seperate tasks, one which makes the
 current data in the Ustr undefined and the second which adds undefined data
 to the ustr to accomodate the desired length.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_sub_buf">ustr_sub_buf()</a>
<br>Returns: Success or failure <br>Type: int 
</td></tr><tr><td>Parameter<strong>[1]</strong>: Pointer to a pointer to a Ustr<br>Type<strong>[1]</strong>: struct Ustr **
</td></tr><tr><td>Parameter<strong>[2]</strong>: Position where to start substitution<br>Type<strong>[2]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[3]</strong>: Buffer containing substitution string <br>Type<strong>[3]</strong>: const void *
</td></tr><tr><td>Parameter<strong>[4]</strong>: Length of buffer<br>Type<strong>[4]</strong>: size_t
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works as if you had called <a href="functions.html#ustr_sub_undef">ustr_sub_undef()</a> and then copied the
 data into the new undefined space.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_sub_cstr">ustr_sub_cstr()</a>
<br>Returns: success or failure <br>Type: int 
</td></tr><tr><td>Parameter<strong>[1]</strong>: Pointer to a pointer to a Ustr<br>Type<strong>[1]</strong>: struct Ustr **
</td></tr><tr><td>Parameter<strong>[2]</strong>: Position where to start substitution<br>Type<strong>[2]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[3]</strong>: A pointer to a constant C-style string, which is the substitution<br>Type<strong>[3]</strong>: const char *
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works like <a href="functions.html#ustr_sub_buf">ustr_sub_buf()</a> but the length is worked out
 automatically by strlen().


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="USTR_SUB_OSTR">USTR_SUB_OSTR()</a>
<br>Returns: Success or failure<br>Type: int 
</td></tr><tr><td>Parameter<strong>[1]</strong>: Pointer to a pointer to a <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: struct Ustr **
</td></tr><tr><td>Parameter<strong>[2]</strong>: Position where to start substitution<br>Type<strong>[2]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[3]</strong>: A constant C-style string<br>Type<strong>[3]</strong>: const char []
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works as if you had called <a href="functions.html#ustr_sub_buf">ustr_sub_buf()</a> and passed
 sizeof() - 1 as the length.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="USTR_SUB_OBJ">USTR_SUB_OBJ()</a>
<br>Returns: Success or failure<br>Type: int 
</td></tr><tr><td>Parameter<strong>[1]</strong>: Pointer to a pointer to a <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: struct Ustr **
</td></tr><tr><td>Parameter<strong>[2]</strong>: Position where to start substitution<br>Type<strong>[2]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[3]</strong>: A symbol<br>Type<strong>[3]</strong>: ...
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works as if you had called <a href="functions.html#ustr_sub_buf">ustr_sub_buf()</a> and passed
 sizeof() as the length.

</td></tr><tr><td><strong>Note:</strong></td></tr><tr><td><p>
</p><p>  In most cases you'll want to use <a href="functions.html#USTR_SUB_OSTR">USTR_SUB_OSTR()</a>.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_sub">ustr_sub()</a>
<br>Returns: Success or failure<br>Type: int 
</td></tr><tr><td>Parameter<strong>[1]</strong>: Pointer to a pointer to a <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: struct Ustr **
</td></tr><tr><td>Parameter<strong>[2]</strong>: Position where to start substitution<br>Type<strong>[2]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[3]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[3]</strong>: const struct Ustr *
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works as if you had called <a href="functions.html#ustr_sub_buf">ustr_sub_buf()</a> with the
 <a href="functions.html#ustr_cstr">ustr_cstr()</a> and <a href="functions.html#ustr_len">ustr_len()</a> values of the <a href="design.html">Ustr string</a> to be added.
 The exception being if you substitute a ustr into itself, while only having a
 single reference count, the simple method could access a free'd ustr data, but
 this function just works.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_sub_subustr">ustr_sub_subustr()</a>
<br>Returns: Success or failure<br>Type: int 
</td></tr><tr><td>Parameter<strong>[1]</strong>: Pointer to a pointer to a <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: struct Ustr **
</td></tr><tr><td>Parameter<strong>[2]</strong>: Position where to start substitution<br>Type<strong>[2]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[3]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[3]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[4]</strong>: Position in the Ustr<br>Type<strong>[4]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[5]</strong>: Length to substitute from the Ustr<br>Type<strong>[5]</strong>: size_t
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function mostly as if you had called <a href="functions.html#ustr_sub_buf">ustr_sub_buf()</a> with the
 <a href="functions.html#ustr_cstr">ustr_cstr()</a> + position - 1 and length values of the <a href="design.html">Ustr string</a> to be insed.
 The exception being if you insert a ustr to itself, while only having a single
 reference count, the simple method would access a free'd ustr data, but this
 function just works.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_sc_sub_undef">ustr_sc_sub_undef()</a>
<br>Returns: Success or failure<br>Type: int 
</td></tr><tr><td>Parameter<strong>[1]</strong>: Pointer to a pointer to a Ustr<br>Type<strong>[1]</strong>: struct Ustr **
</td></tr><tr><td>Parameter<strong>[2]</strong>: Position where to start substitution<br>Type<strong>[2]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[3]</strong>: Length of substitution<br>Type<strong>[3]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[4]</strong>: Length of undefined data<br>Type<strong>[4]</strong>: size_t
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works as if you had done <a href="functions.html#ustr_del_subustr">ustr_del_subustr()</a> followed by
 <a href="functions.html#ustr_ins_undef">ustr_ins_undef()</a>, however it is significantly more efficient.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_sc_sub_buf">ustr_sc_sub_buf()</a>
<br>Returns: Success or failure <br>Type: int 
</td></tr><tr><td>Parameter<strong>[1]</strong>: Pointer to a pointer to a Ustr<br>Type<strong>[1]</strong>: struct Ustr **
</td></tr><tr><td>Parameter<strong>[2]</strong>: Position where to start substitution<br>Type<strong>[2]</strong>: size_t 
</td></tr><tr><td>Parameter<strong>[3]</strong>: Length of substitution<br>Type<strong>[3]</strong>: size_t 
</td></tr><tr><td>Parameter<strong>[4]</strong>: Buffer containting substitute data<br>Type<strong>[4]</strong>: const void *
</td></tr><tr><td>Parameter<strong>[5]</strong>: Length of Buffer<br>Type<strong>[5]</strong>: size_t 
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function will substitute a specific number of characters in a Ustr with
 the data from a buffer, this function does the job of one or more of
 <a href="functions.html#ustr_add_buf">ustr_add_buf()</a>, <a href="functions.html#ustr_sub_buf">ustr_sub_buf()</a> and <a href="functions.html#ustr_del">ustr_del()</a>.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_sc_sub_cstr">ustr_sc_sub_cstr()</a>
<br>Returns: Success or failure <br>Type: int 
</td></tr><tr><td>Parameter<strong>[1]</strong>: Pointer to a pointer to a Ustr<br>Type<strong>[1]</strong>: struct Ustr **
</td></tr><tr><td>Parameter<strong>[2]</strong>: Position where to start replacement <br>Type<strong>[2]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[3]</strong>: Length of substitution<br>Type<strong>[3]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[4]</strong>: A pointer to a constant C-style string, containing spanning bytes<br>Type<strong>[4]</strong>: const char *
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works like <a href="functions.html#ustr_sc_sub_buf">ustr_sc_sub_buf()</a> but the length is worked out
 automatically by strlen().


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_sc_sub">ustr_sc_sub()</a>
<br>Returns: success or failure <br>Type: int 
</td></tr><tr><td>Parameter<strong>[1]</strong>: Pointer to a pointer to a Ustr<br>Type<strong>[1]</strong>: struct Ustr **
</td></tr><tr><td>Parameter<strong>[2]</strong>: Position where to start substitution<br>Type<strong>[2]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[3]</strong>: Length of substitution<br>Type<strong>[3]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[4]</strong>: Pointer to a Ustr containing the substitute string<br>Type<strong>[4]</strong>: const struct Ustr *
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works as if you had called <a href="functions.html#ustr_sc_sub_buf">ustr_sc_sub_buf()</a> with the
 <a href="functions.html#ustr_cstr">ustr_cstr()</a> and <a href="functions.html#ustr_len">ustr_len()</a> values of the <a href="design.html">Ustr string</a> to be added.
 The exception being if you substitute a ustr into itself, while only having a
 single reference count, the simple method could access a free'd ustr data, but
 this function just works.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_sc_sub_subustr">ustr_sc_sub_subustr()</a>
<br>Returns: Success or failure <br>Type: int 
</td></tr><tr><td>Parameter<strong>[1]</strong>: Pointer to a pointer to a Ustr<br>Type<strong>[1]</strong>: struct Ustr **
</td></tr><tr><td>Parameter<strong>[2]</strong>: Position where to start substitution<br>Type<strong>[2]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[3]</strong>: Length of substitution<br>Type<strong>[3]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[4]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[4]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[5]</strong>: Position in the Ustr<br>Type<strong>[5]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[6]</strong>: Length to substitute from the Ustr<br>Type<strong>[6]</strong>: size_t
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function mostly as if you had called <a href="functions.html#ustr_sc_sub_buf">ustr_sc_sub_buf()</a> with the
 <a href="functions.html#ustr_cstr">ustr_cstr()</a> + position - 1 and length values of the <a href="design.html">Ustr string</a> to be insed.
 The exception being if you insert a ustr to itself, while only having a single
 reference count, the simple method would access a free'd ustr data, but this
 function just works.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="USTR_SC_SUB_OSTR">USTR_SC_SUB_OSTR()</a>
<br>Returns: Success or failure<br>Type: int 
</td></tr><tr><td>Parameter<strong>[1]</strong>: Pointer to a pointer to a <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: struct Ustr **
</td></tr><tr><td>Parameter<strong>[2]</strong>: Position where to start substitution<br>Type<strong>[2]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[3]</strong>: Length of substitution<br>Type<strong>[3]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[4]</strong>: A constant C-style string<br>Type<strong>[4]</strong>: const char []
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works as if you had called <a href="functions.html#ustr_sc_sub_buf">ustr_sc_sub_buf()</a> and passed
 sizeof() - 1 as the length.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="USTR_SC_SUB_OBJ">USTR_SC_SUB_OBJ()</a>
<br>Returns: Success or failure<br>Type: int 
</td></tr><tr><td>Parameter<strong>[1]</strong>: Pointer to a pointer to a <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: struct Ustr **
</td></tr><tr><td>Parameter<strong>[2]</strong>: Position where to start substitution<br>Type<strong>[2]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[3]</strong>: Length of substitution<br>Type<strong>[3]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[4]</strong>: A symbol<br>Type<strong>[4]</strong>: ...
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works as if you had called <a href="functions.html#ustr_sc_sub_buf">ustr_sc_sub_buf()</a> and passed
 sizeof() as the length.

</td></tr><tr><td><strong>Note:</strong></td></tr><tr><td><p>
</p><p>  In most cases you'll want to use <a href="functions.html#USTR_SUB_OSTR">USTR_SUB_OSTR()</a>.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_replace_buf">ustr_replace_buf()</a>
<br>Returns: Number of tokens replaced <br>Type: size_t 
</td></tr><tr><td>Parameter<strong>[1]</strong>: Pointer to a pointer to a Ustr (haystack)<br>Type<strong>[1]</strong>: struct Ustr **
</td></tr><tr><td>Parameter<strong>[2]</strong>: Buffer containting search data<br>Type<strong>[2]</strong>: const void *
</td></tr><tr><td>Parameter<strong>[3]</strong>: Length of search buffer<br>Type<strong>[3]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[4]</strong>: Buffer containting replacement data<br>Type<strong>[4]</strong>: const void *
</td></tr><tr><td>Parameter<strong>[5]</strong>: Length of replacement buffer<br>Type<strong>[5]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[6]</strong>: Maximum number of matches to replace (0 for unlimited)<br>Type<strong>[6]</strong>: size_t
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function scans the &quot;haystack&quot; (Parameter[1]) for &quot;needle&quot; (Parameter[2])
 and replaces max_replacements (Parameter[6]) matches with the
 "replacement" (Parameter[4]).

</td></tr><tr><td><strong>Note:</strong></td></tr><tr><td><p>
</p><p>  If max_replacements (Parameter[6]) is 0, this function will replace ALL
 occurrences.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_replace_cstr">ustr_replace_cstr()</a>
<br>Returns: Number of tokens replaced <br>Type: size_t 
</td></tr><tr><td>Parameter<strong>[1]</strong>: Pointer to a pointer to a Ustr (haystack)<br>Type<strong>[1]</strong>: struct Ustr **
</td></tr><tr><td>Parameter<strong>[2]</strong>: A pointer to a constant C-style string, containing search bytes<br>Type<strong>[2]</strong>: const char *
</td></tr><tr><td>Parameter<strong>[3]</strong>: A pointer to a constant C-style string, containing replacement bytes<br>Type<strong>[3]</strong>: const char *
</td></tr><tr><td>Parameter<strong>[4]</strong>: Maximum number of matches to replace (0 for unlimited)<br>Type<strong>[4]</strong>: size_t
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works like <a href="functions.html#ustr_replace_buf">ustr_replace_buf()</a> but gets the lengths for the
 buffer automatically from strlen().


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_replace">ustr_replace()</a>
<br>Returns: Number of tokens replaced <br>Type: int 
</td></tr><tr><td>Parameter<strong>[1]</strong>: Pointer to a pointer to a Ustr (haystack)<br>Type<strong>[1]</strong>: struct Ustr **
</td></tr><tr><td>Parameter<strong>[2]</strong>: Ustr to search for (needle)<br>Type<strong>[2]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[3]</strong>: Ustr to replace needle with<br>Type<strong>[3]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[4]</strong>: Maximum number of matches to replace (0 for unlimited)<br>Type<strong>[4]</strong>: size_t
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works like <a href="functions.html#ustr_replace_buf">ustr_replace_buf()</a> but gets the lengths from the
 ustr automatically.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_replace_rep_chr">ustr_replace_rep_chr()</a>
<br>Returns: number of replacements made<br>Type: size_t
</td></tr><tr><td>Parameter<strong>[1]</strong>: pointer to a pointer to a Ustr to be modified<br>Type<strong>[1]</strong>: struct Ustr **ps1
</td></tr><tr><td>Parameter<strong>[2]</strong>: character to replace<br>Type<strong>[2]</strong>: char
</td></tr><tr><td>Parameter<strong>[3]</strong>: number of characters to replace<br>Type<strong>[3]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[4]</strong>: character to replace with<br>Type<strong>[4]</strong>: char
</td></tr><tr><td>Parameter<strong>[5]</strong>: number of characters to replace with<br>Type<strong>[5]</strong>: size_t nlen
</td></tr><tr><td>Parameter<strong>[6]</strong>: maximum number of replacements to make (use 0 for unlimited)<br>Type<strong>[6]</strong>: size_t lim
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function replaces a repeating sequence of characters with another
 repeating sequence of characters. 

  For example...
</p><pre>
  Ustr *data = ustr_dup_cstr("xxxBxxCxDxxx");
  ustr_replace_rep_chr(&data,'x',2,'y',1, 0)

</pre><p> ...would change data to be "yxByCxDyx".


</td></tr><tr><td><strong>Note:</strong></td></tr><tr><td><p>
</p><p>  Changing the same letter the same number of times is considered a No-op
 since it is a vast performance improvement this way. So passing in 
 (&data,'y',2,'y',2 ,0) will have a return value of 0 and the string will be
 unchanged.


</td></tr></table><table width="90%"><tr><td class="sect"><h2><a id="Splitting%20a%20Ustr">Splitting a Ustr</a></h2>
</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_split_buf">ustr_split_buf()</a>
<br>Returns: pointer to a Ustr representing the next token<br>Type: struct Ustr *
</td></tr><tr><td>Parameter<strong>[1]</strong>: Pointer to a constant Ustr to be split<br>Type<strong>[1]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[2]</strong>: Pointer to an offset<br>Type<strong>[2]</strong>: size_t *
</td></tr><tr><td>Parameter<strong>[3]</strong>: Buffer to use as split search pattern <br>Type<strong>[3]</strong>: const void *
</td></tr><tr><td>Parameter<strong>[4]</strong>: Length of buffer<br>Type<strong>[4]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[5]</strong>: Pointer to a Ustr to be used as the return value<br>Type<strong>[5]</strong>: struct Ustr *
</td></tr><tr><td>Parameter<strong>[6]</strong>: Flags with the prefix USTR_FLAG_SPLIT_<br>Type<strong>[6]</strong>: unsigned int
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works in a manner similar to strtok(). Each time the function
 is called, the string inside of the buffer (Parameter[3]) is used as a search
 pattern at which to split. If the pattern is not found, the entire string
 will be returned. A <a href="constants.html#USTR_NULL">USTR_NULL</a> return value indicates there are no more
 tokens remaining.
</p><p>  Parameter[5] is a a pointer to a Ustr where the return value will be placed.
 Passing a <a href="constants.html#USTR_NULL">USTR_NULL</a> to this parameter will cause the string to be allocated
 and <b>MUST</b> be freed <b>manually</b>. If, however, you pass in a non-null Ustr to
 this parameter, each call to <a href="functions.html#ustr_split_buf">ustr_split_buf()</a> will free what is in this
 pointer and place the new token there (when <a href="constants.html#USTR_NULL">USTR_NULL</a> is returned, nothing
 needs to be free'd).
  For example, given...
</p><pre>
  Ustr *data = ...;
  Ustr *tok = USTR_NULL;
  const char *sep = ",";
  size_t off = 0;
  unsigned int flags = USTR_FLAGS_SPLIT_DEF;

</pre><p> ...there are two options...
</p><pre>
  while ((tok = ustr_split_buf(data, &off, sep, strlen(sep), tok, flags)))
  {
    /* Do something with tok -- but next iteration of the loop will free
     * and overwrite tok, so you must ustr_dup() if you want to keep it */
  }
  /* tok is now NULL again after the loop */

</pre><p> ...or...
</p><pre>
  while ((tok = ustr_split_buf(data, &off, sep, strlen(sep), USTR_NULL, flags)))
  {
    /* Do something with tok, and it will NOT be freed in the next iteration of
     * the loop */
      ustr_free(tok); /* have to free to avoid mem leaks */
  }

</pre><p> ...the former of which being the safer option.

</td></tr><tr><td><strong>Note:</strong></td></tr><tr><td><p>
</p><p>  There are several flags that will alter the behaviour of this function,
 all of which have a common with the default being <a href="constants.html#USTR_FLAG_SPLIT_DEF">USTR_FLAG_SPLIT_DEF</a>.
</p><p>  If you are calling this function directly, it is very likely that you'd want
 to use <a href="functions.html#ustr_split_cstr">ustr_split_cstr()</a> instead.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_split">ustr_split()</a>
<br>Returns: Pointer to a Ustr representing the next token<br>Type: struct Ustr *
</td></tr><tr><td>Parameter<strong>[1]</strong>: Pointer to a constant Ustr to be split<br>Type<strong>[1]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[2]</strong>: Pointer to an offset variable<br>Type<strong>[2]</strong>: size_t *
</td></tr><tr><td>Parameter<strong>[3]</strong>: Pointer to a constant Ustr to use as the split search pattern<br>Type<strong>[3]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[4]</strong>: Pointer to a Ustr where the return value will be placed<br>Type<strong>[4]</strong>: struct Ustr *
</td></tr><tr><td>Parameter<strong>[5]</strong>: Flags<br>Type<strong>[5]</strong>: unsigned int
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>   Works like <a href="functions.html#ustr_split_buf">ustr_split_buf()</a> but takes a Ustr as the split search pattern
</p><p>  instead.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_split_cstr">ustr_split_cstr()</a>
<br>Returns: Pointer to a Ustr representing the next token<br>Type: struct Ustr *
</td></tr><tr><td>Parameter<strong>[1]</strong>: Pointer to a constant Ustr to be split<br>Type<strong>[1]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[2]</strong>: Pointer to an offset variable<br>Type<strong>[2]</strong>: size_t *
</td></tr><tr><td>Parameter<strong>[3]</strong>: C string to use as split search pattern<br>Type<strong>[3]</strong>: const char *
</td></tr><tr><td>Parameter<strong>[4]</strong>: Pointer to a Ustr where the return value will be placed<br>Type<strong>[4]</strong>: struct Ustr *
</td></tr><tr><td>Parameter<strong>[5]</strong>: Flags<br>Type<strong>[5]</strong>: unsigned int
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  Works like <a href="functions.html#ustr_split_buf">ustr_split_buf()</a> but takes a C string as the split search
 pattern, and so gets the length via. strlen().


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_split_spn_chrs">ustr_split_spn_chrs()</a>
<br>Returns: Pointer to a Ustr representing the next token<br>Type: struct Ustr *
</td></tr><tr><td>Parameter<strong>[1]</strong>: Pointer to a Ustr to be split<br>Type<strong>[1]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[2]</strong>: Pointer to an offset variable<br>Type<strong>[2]</strong>: size_t *
</td></tr><tr><td>Parameter<strong>[3]</strong>: String representing a set of bytes to use as split chars<br>Type<strong>[3]</strong>: const char *
</td></tr><tr><td>Parameter<strong>[4]</strong>: Length of the string of set of bytes<br>Type<strong>[4]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[5]</strong>: Pointer to a Ustr where the return value will be placed<br>Type<strong>[5]</strong>: struct Ustr *
</td></tr><tr><td>Parameter<strong>[6]</strong>: flags<br>Type<strong>[6]</strong>: unsigned int
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  Works like <a href="functions.html#ustr_split_buf">ustr_split_buf()</a> but uses the individual ASCII bytes in the
 separator string (Parameter[3]) as search patterns. It will split if <b>ANY</b> of
 these individual characters are matched (much like strtok()). For example:
 if splitting "this, is,a test" with the separator string ", " the tokens
 returned would be {"this" "is" "a" "test"};

</td></tr><tr><td><strong>Note:</strong></td></tr><tr><td><p>
</p><p>  If you are calling this function directly, it is very likely that you'd want
 to use <a href="functions.html#ustr_split_spn_cstr">ustr_split_spn_cstr()</a> instead.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_split_spn_cstr">ustr_split_spn_cstr()</a>
<br>Returns: Pointer to a Ustr representing the next token<br>Type: struct Ustr *
</td></tr><tr><td>Parameter<strong>[1]</strong>: Pointer to a Ustr to be split<br>Type<strong>[1]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[2]</strong>: Pointer to an offset variable<br>Type<strong>[2]</strong>: size_t *
</td></tr><tr><td>Parameter<strong>[3]</strong>: String representing a set of bytes to use as split chars<br>Type<strong>[3]</strong>: const char *
</td></tr><tr><td>Parameter<strong>[4]</strong>: Pointer to a Ustr where the return value will be placed<br>Type<strong>[4]</strong>: struct Ustr *
</td></tr><tr><td>Parameter<strong>[5]</strong>: flags<br>Type<strong>[5]</strong>: unsigned int
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  Works like <a href="functions.html#ustr_split_spn_chrs">ustr_split_spn_chrs()</a> but gets the length automatically via.
 strlen().


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_split_spn">ustr_split_spn()</a>
<br>Returns: Pointer to a Ustr representing the next token<br>Type: struct Ustr *
</td></tr><tr><td>Parameter<strong>[1]</strong>: Pointer to a constant Ustr to be split<br>Type<strong>[1]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[2]</strong>: Pointer to an offset variable<br>Type<strong>[2]</strong>: size_t *
</td></tr><tr><td>Parameter<strong>[3]</strong>: Pointer to a constant Ustr to use as the split search pattern<br>Type<strong>[3]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[4]</strong>: Pointer to a Ustr where the return value will be placed<br>Type<strong>[4]</strong>: struct Ustr *
</td></tr><tr><td>Parameter<strong>[5]</strong>: Flags<br>Type<strong>[5]</strong>: unsigned int
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  Works like <a href="functions.html#ustr_split_spn_chrs">ustr_split_spn_chrs()</a> but takes a Ustr as the split chars instead.


</td></tr></table><table width="90%"><tr><td class="sect"><h2><a id="Dealing%20with%20UTF%2d8%20in%20a%20Ustr">Dealing with UTF-8 in a Ustr</a></h2>
</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_utf8_valid">ustr_utf8_valid()</a>
<br>Returns: A boolean flag of either <a href="constants.html#USTR_TRUE">USTR_TRUE</a> or USTR_FALSE<br>Type: int 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: const struct Ustr *
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function tries it's best to find out if the string is a valid utf-8
 string.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_utf8_len">ustr_utf8_len()</a>
<br>Returns: The number of the utf-8 characters in the Ustr<br>Type: size_t 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: const struct Ustr *
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function counts the number of utf-8 characters inn the Ustr.

</td></tr><tr><td><strong>Note:</strong></td></tr><tr><td><p>
</p><p>  This function gives undefined answers on strings that aren't utf-8 valid.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_utf8_width">ustr_utf8_width()</a>
<br>Returns: ssize_t <br>Type: ssize_t 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: const struct Ustr *
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function returns the visible width of the string, assuming it is a valid
 utf-8 string. This is like converting to wide characters and using wcwidth().


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_utf8_chars2bytes">ustr_utf8_chars2bytes()</a>
<br>Returns: Length of span in bytes <br>Type: size_t 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[2]</strong>: Position of a span in utf-8 characters<br>Type<strong>[2]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[3]</strong>: Length of a span in utf-8 characters<br>Type<strong>[3]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[4]</strong>: Returns the position of the span in bytes<br>Type<strong>[4]</strong>: size_t *
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function converts a span, in utf-8 characters, to the same span in bytes.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_utf8_bytes2chars">ustr_utf8_bytes2chars()</a>
<br>Returns: Returns the position of a span in utf-8 characters<br>Type: size_t 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[2]</strong>: Position of a span in bytes<br>Type<strong>[2]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[3]</strong>: Length of a span in bytes<br>Type<strong>[3]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[4]</strong>: Returns length of a span in utf-8 characters<br>Type<strong>[4]</strong>: size_t *
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function converts a span, in bytes, to the same span in utf-8 characters.

</td></tr><tr><td><strong>Note:</strong></td></tr><tr><td><p>
</p><p>  Because a byte span can start or end within a utf-8 character, converting the
 return values back into bytes via. <a href="functions.html#ustr_utf8_chars2bytes">ustr_utf8_chars2bytes()</a> may make the span
 be slightly bigger (position slightly earlier, and the length slightly longer).


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_sc_utf8_reverse">ustr_sc_utf8_reverse()</a>
<br>Returns: Success or failure<br>Type: int
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a pointer to a <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: struct Ustr **
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function reverses the utf-8 characters in the <a href="design.html">Ustr string</a>, assuming it
 is a valid utf-8 string, so the last one becomes the first and the second to
 last becomes the second etc.


</td></tr></table><table width="90%"><tr><td class="sect"><h2><a id="Parsing%20ASCII%20integer%20numbers%20from%20a%20Ustr">Parsing ASCII integer numbers from a Ustr</a></h2>
</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_parse_uintmaxx">ustr_parse_uintmaxx()</a>
<br>Returns: Parsed number, or zero on error<br>Type: uintmax_t 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[2]</strong>: Offset within string to start parsing at<br>Type<strong>[2]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[3]</strong>: Base (2-36) and flags, starting with USTR_FLAG_PARSE_NUM_<br>Type<strong>[3]</strong>: unsigned int
</td></tr><tr><td>Parameter<strong>[4]</strong>: Absolute minimum value<br>Type<strong>[4]</strong>: uintmax_t
</td></tr><tr><td>Parameter<strong>[5]</strong>: Absolute maximum value<br>Type<strong>[5]</strong>: uintmax_t
</td></tr><tr><td>Parameter<strong>[6]</strong>: Thousands separator<br>Type<strong>[6]</strong>: const char *
</td></tr><tr><td>Parameter<strong>[7]</strong>: Return length of parsed number<br>Type<strong>[7]</strong>: size_t *
</td></tr><tr><td>Parameter<strong>[8]</strong>: Return error code, starting with USTR_TYPE_PARSE_NUM_ERR_<br>Type<strong>[8]</strong>: unsigned int *
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function parses an ASCII representation of a number from a
 Ustr (Parameter[1]) starting at the offset (Parameter[2]).

</td></tr><tr><td><strong>Note:</strong></td></tr><tr><td><p>
</p><p>  If stdint.h isn't available this function won't be available.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_parse_uintmax">ustr_parse_uintmax()</a>
<br>Returns: Parsed number, or zero on error<br>Type: uintmax_t 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[2]</strong>: Offset within string to start parsing at<br>Type<strong>[2]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[3]</strong>: Base (2-36) and flags, starting with USTR_FLAG_PARSE_NUM_<br>Type<strong>[3]</strong>: unsigned int
</td></tr><tr><td>Parameter<strong>[4]</strong>: Return length of parsed number<br>Type<strong>[4]</strong>: size_t *
</td></tr><tr><td>Parameter<strong>[5]</strong>: Return error code, starting with USTR_TYPE_PARSE_NUM_ERR_<br>Type<strong>[5]</strong>: unsigned int *
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works like <a href="functions.html#ustr_parse_uintmaxx">ustr_parse_uintmaxx()</a> with the minimum and maximum
 values taken as 0 and UINTMAX_MAX, and the thousands separator as "_".

</td></tr><tr><td><strong>Note:</strong></td></tr><tr><td><p>
</p><p>  If stdint.h isn't available this function won't be available.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_parse_intmax">ustr_parse_intmax()</a>
<br>Returns: Parsed number, or zero on error<br>Type: intmax_t 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[2]</strong>: Offset within string to start parsing at<br>Type<strong>[2]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[3]</strong>: Base (2-36) and flags, starting with USTR_FLAG_PARSE_NUM_<br>Type<strong>[3]</strong>: unsigned int
</td></tr><tr><td>Parameter<strong>[4]</strong>: Return length of parsed number<br>Type<strong>[4]</strong>: size_t *
</td></tr><tr><td>Parameter<strong>[5]</strong>: Return error code, starting with USTR_TYPE_PARSE_NUM_ERR_<br>Type<strong>[5]</strong>: unsigned int *
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works like <a href="functions.html#ustr_parse_uintmaxx">ustr_parse_uintmaxx()</a> with the minimum and maximum
 values taken as -INTMAX_MIN and INTMAX_MAX, and the thousands separator as "_".

</td></tr><tr><td><strong>Note:</strong></td></tr><tr><td><p>
</p><p>  If stdint.h isn't available this function won't be available.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_parse_ulongx">ustr_parse_ulongx()</a>
<br>Returns: Parsed number, or zero on error<br>Type: unsigned long 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[2]</strong>: Offset within string to start parsing at<br>Type<strong>[2]</strong>:  size_t
</td></tr><tr><td>Parameter<strong>[3]</strong>: Base (2-36) and flags, starting with USTR_FLAG_PARSE_NUM_<br>Type<strong>[3]</strong>:  unsigned int
</td></tr><tr><td>Parameter<strong>[4]</strong>: Absolute minimum value<br>Type<strong>[4]</strong>:  unsigned long
</td></tr><tr><td>Parameter<strong>[5]</strong>: Absolute maximum value<br>Type<strong>[5]</strong>:  unsigned long
</td></tr><tr><td>Parameter<strong>[6]</strong>: Thousands separator<br>Type<strong>[6]</strong>: const char *
</td></tr><tr><td>Parameter<strong>[7]</strong>: Return length of parsed number<br>Type<strong>[7]</strong>:  size_t *
</td></tr><tr><td>Parameter<strong>[8]</strong>: Return error code, starting with USTR_TYPE_PARSE_NUM_ERR_<br>Type<strong>[8]</strong>: unsigned int *
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works like <a href="functions.html#ustr_parse_uintmaxx">ustr_parse_uintmaxx()</a> but returns an unsigned long,
 it is always available even when stdint.h isn't.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_parse_ulong">ustr_parse_ulong()</a>
<br>Returns: Parsed number, or zero on error<br>Type: unsigned long 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[2]</strong>: Offset within string to start parsing at<br>Type<strong>[2]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[3]</strong>: Base (2-36) and flags, starting with USTR_FLAG_PARSE_NUM_<br>Type<strong>[3]</strong>: unsigned int
</td></tr><tr><td>Parameter<strong>[4]</strong>: Return length of parsed number<br>Type<strong>[4]</strong>: size_t *
</td></tr><tr><td>Parameter<strong>[5]</strong>: Return error code, starting with USTR_TYPE_PARSE_NUM_ERR_<br>Type<strong>[5]</strong>: unsigned int *
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works like <a href="functions.html#ustr_parse_ulongx">ustr_parse_ulongx()</a> with the minimum and maximum
 values taken as 0 and ULONG_MAX, and the thousands separator as "_".


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_parse_long">ustr_parse_long()</a>
<br>Returns: Parsed number, or zero on error<br>Type: long 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[2]</strong>: Offset within string to start parsing at<br>Type<strong>[2]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[3]</strong>: Base (2-36) and flags, starting with USTR_FLAG_PARSE_NUM_<br>Type<strong>[3]</strong>: unsigned int
</td></tr><tr><td>Parameter<strong>[4]</strong>: Return length of parsed number<br>Type<strong>[4]</strong>: size_t *
</td></tr><tr><td>Parameter<strong>[5]</strong>: Return error code, starting with USTR_TYPE_PARSE_NUM_ERR_<br>Type<strong>[5]</strong>: unsigned int *
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works like <a href="functions.html#ustr_parse_ulongx">ustr_parse_ulongx()</a> with the minimum and maximum
 values taken as -LONG_MIN and LONG_MAX, and the thousands separator as "_".


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_parse_uint">ustr_parse_uint()</a>
<br>Returns: Parsed number, or zero on error<br>Type: unsigned int 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[2]</strong>: Offset within string to start parsing at<br>Type<strong>[2]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[3]</strong>: Base (2-36) and flags, starting with USTR_FLAG_PARSE_NUM_<br>Type<strong>[3]</strong>: unsigned int
</td></tr><tr><td>Parameter<strong>[4]</strong>: Return length of parsed number<br>Type<strong>[4]</strong>: size_t *
</td></tr><tr><td>Parameter<strong>[5]</strong>: Return error code, starting with USTR_TYPE_PARSE_NUM_ERR_<br>Type<strong>[5]</strong>: unsigned int *
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works like <a href="functions.html#ustr_parse_ulongx">ustr_parse_ulongx()</a> with the minimum and maximum
 values taken as 0 and UINT_MAX, and the thousands separator as "_".


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_parse_int">ustr_parse_int()</a>
<br>Returns: Parsed number, or zero on error<br>Type: int 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[2]</strong>: Offset within string to start parsing at<br>Type<strong>[2]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[3]</strong>: Base (2-36) and flags, starting with USTR_FLAG_PARSE_NUM_<br>Type<strong>[3]</strong>: unsigned int
</td></tr><tr><td>Parameter<strong>[4]</strong>: Return length of parsed number<br>Type<strong>[4]</strong>: size_t *
</td></tr><tr><td>Parameter<strong>[5]</strong>: Return error code, starting with USTR_TYPE_PARSE_NUM_ERR_<br>Type<strong>[5]</strong>: unsigned int *
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works like <a href="functions.html#ustr_parse_ulongx">ustr_parse_ulongx()</a> with the minimum and maximum
 values taken as -INT_MIN and INT_MAX, and the thousands separator as "_".


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_parse_ushort">ustr_parse_ushort()</a>
<br>Returns: Parsed number, or zero on error<br>Type: unsigned short 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[2]</strong>: Offset within string to start parsing at<br>Type<strong>[2]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[3]</strong>: Base (2-36) and flags, starting with USTR_FLAG_PARSE_NUM_<br>Type<strong>[3]</strong>: unsigned int
</td></tr><tr><td>Parameter<strong>[4]</strong>: Return length of parsed number<br>Type<strong>[4]</strong>: size_t *
</td></tr><tr><td>Parameter<strong>[5]</strong>: Return error code, starting with USTR_TYPE_PARSE_NUM_ERR_<br>Type<strong>[5]</strong>: unsigned int *
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works like <a href="functions.html#ustr_parse_ulongx">ustr_parse_ulongx()</a> with the minimum and maximum
 values taken as 0 and USHRT_MAX, and the thousands separator as "_".


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_parse_short">ustr_parse_short()</a>
<br>Returns: Parsed number, or zero on error<br>Type: short 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[2]</strong>: Offset within string to start parsing at<br>Type<strong>[2]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[3]</strong>: Base (2-36) and flags, starting with USTR_FLAG_PARSE_NUM_<br>Type<strong>[3]</strong>: unsigned int
</td></tr><tr><td>Parameter<strong>[4]</strong>: Return length of parsed number<br>Type<strong>[4]</strong>: size_t *
</td></tr><tr><td>Parameter<strong>[5]</strong>: Return error code, starting with USTR_TYPE_PARSE_NUM_ERR_<br>Type<strong>[5]</strong>: unsigned int *
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works like <a href="functions.html#ustr_parse_ulongx">ustr_parse_ulongx()</a> with the minimum and maximum
 values taken as -SHRT_MIN and SHRT_MAX, and the thousands separator as "_".


</td></tr></table><table width="90%"><tr><td class="sect"><h2><a id="Misc%20shortcut%20helper%20functions%20for%20Ustrs">Misc shortcut helper functions for Ustrs</a></h2>
</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_sc_ensure_owner">ustr_sc_ensure_owner()</a>
<br>Returns: Success or failure<br>Type: int 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a pointer to a <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: struct Ustr **
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function makes sure that the <a href="design.html">Ustr string</a> is owned when it returns (Ie.
 <a href="functions.html#ustr_owner">ustr_owner()</a> returns <a href="constants.html#USTR_TRUE">USTR_TRUE</a>), or it fails to allocate.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_sc_wstr">ustr_sc_wstr()</a>
<br>Returns: Writable pointer to the start of data in the Ustr, or NULL<br>Type: char *
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a pointer to a <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: struct Ustr **
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works like calling <a href="functions.html#ustr_sc_ensure_owner">ustr_sc_ensure_owner()</a>, to make sure the
 <a href="design.html">Ustr string</a> is writable, and if that succeeds it returns <a href="functions.html#ustr_wstr">ustr_wstr()</a>. On
 failure it returns NULL.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_sc_export_subustr">ustr_sc_export_subustr()</a>
<br>Returns: A pointer to newly allocated block of memory<br>Type: char *
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[2]</strong>: Position in the Ustr<br>Type<strong>[2]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[3]</strong>: Length to export from the Ustr<br>Type<strong>[3]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[4]</strong>: Allocation function (like malloc)<br>Type<strong>[4]</strong>: void *(*)(size_t)
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function allocates a block of memory of size Length (Parameter[3]) + 1 
 using the provided allocation function (Parameter[4]) and copies the data
 starting from Position (Parameter[2]) within the ustr.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_sc_export">ustr_sc_export()</a>
<br>Returns: A pointer to newly allocated block of memory<br>Type: char *
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[2]</strong>: Allocation function (like malloc)<br>Type<strong>[2]</strong>: void *(*)(size_t)
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works like calling <a href="functions.html#ustr_sc_export_subustr">ustr_sc_export_subustr()</a> with a position of
 1 and a length of <a href="functions.html#ustr_len">ustr_len()</a>.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustrp_sc_export_subustrp">ustrp_sc_export_subustrp()</a>
<br>Returns: A pointer to newly allocated block of memory<br>Type: char *
</td></tr><tr><td>Parameter<strong>[1]</strong>: Pointer to a <a href="design.html#possibilities">Ustr pool</a> object<br>Type<strong>[1]</strong>: struct Ustr_pool *
</td></tr><tr><td>Parameter<strong>[2]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[2]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[3]</strong>: Position in the Ustr<br>Type<strong>[3]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[4]</strong>: Length to export from the Ustr<br>Type<strong>[4]</strong>: size_t
</td></tr><tr><td>Parameter<strong>[5]</strong>: Allocation function (like malloc), or NULL<br>Type<strong>[5]</strong>: void *(*)(size_t)
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function allocates a block of memory of size Length (Parameter[4]) + 1 
 using either the provided allocation function (Parameter[5]), or from the pool
 object if the allocation function is NUL, and copies the data starting from
 Position (Parameter[3]) within the ustr.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustrp_sc_export">ustrp_sc_export()</a>
<br>Returns: A pointer to newly allocated block of memory<br>Type: char *
</td></tr><tr><td>Parameter<strong>[1]</strong>: Pointer to a <a href="design.html#possibilities">Ustr pool</a> object<br>Type<strong>[1]</strong>: struct Ustr_pool *
</td></tr><tr><td>Parameter<strong>[2]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[2]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[3]</strong>: Allocation function (like malloc)<br>Type<strong>[3]</strong>: void *(*)(size_t)
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works like calling <a href="functions.html#ustrp_sc_export_subustrp">ustrp_sc_export_subustrp()</a> with a position of
 1 and a length of <a href="functions.html#ustrp_len">ustrp_len()</a>.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_sc_reverse">ustr_sc_reverse()</a>
<br>Returns: Success or failure<br>Type: int 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a pointer to a <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: struct Ustr **
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function reverses all the bytes in the <a href="design.html">Ustr string</a>, so the last one
 becomes the first and the second to last becomes the second etc.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_sc_tolower">ustr_sc_tolower()</a>
<br>Returns: Success or failure<br>Type: int 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a pointer to a <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: struct Ustr **
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function changes any ASCII upper case bytes into ASCII lower case bytes.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_sc_toupper">ustr_sc_toupper()</a>
<br>Returns: Success or failure<br>Type: int 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a pointer to a <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: struct Ustr **
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function changes any ASCII lower case bytes into ASCII upper case bytes.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_sc_ltrim_chrs">ustr_sc_ltrim_chrs()</a>
<br>Returns: Success or failure<br>Type: int 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a pointer to a <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: struct Ustr **
</td></tr><tr><td>Parameter<strong>[2]</strong>: Array of bytes, containing trimming data<br>Type<strong>[2]</strong>: const char *
</td></tr><tr><td>Parameter<strong>[3]</strong>: Length of byte data<br>Type<strong>[3]</strong>: size_t
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function deletes the bytes at the begining of the Ustr (Parameter[1])
 that are in the span (Parameter[2]) of the specificed length (parameter[2]).


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_sc_ltrim">ustr_sc_ltrim()</a>
<br>Returns: Success or failure<br>Type: int 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a pointer to a <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: struct Ustr **
</td></tr><tr><td>Parameter<strong>[2]</strong>: A pointer to a constant <a href="design.html">Ustr string</a>, containing trimming bytes<br>Type<strong>[2]</strong>: const struct Ustr *
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works as if you had called <a href="functions.html#ustr_sc_ltrim_chrs">ustr_sc_ltrim_chrs()</a> and passed
 <a href="functions.html#ustr_cstr">ustr_cstr()</a> and <a href="functions.html#ustr_len">ustr_len()</a> values of the <a href="design.html">Ustr string</a> (Parameter[2]).


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_sc_ltrim_cstr">ustr_sc_ltrim_cstr()</a>
<br>Returns: Success or failure<br>Type: int 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a pointer to a <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: struct Ustr **
</td></tr><tr><td>Parameter<strong>[2]</strong>: A pointer to a constant C-style string, containing trimming bytes<br>Type<strong>[2]</strong>: const char *
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works as if you had called <a href="functions.html#ustr_sc_ltrim_chrs">ustr_sc_ltrim_chrs()</a> and passed
 strlen() as the length.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_sc_rtrim_chrs">ustr_sc_rtrim_chrs()</a>
<br>Returns: Success or failure<br>Type: int 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a pointer to a <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: struct Ustr **
</td></tr><tr><td>Parameter<strong>[2]</strong>: Array of bytes, containing trimming data<br>Type<strong>[2]</strong>: const char *
</td></tr><tr><td>Parameter<strong>[3]</strong>: Length of byte data<br>Type<strong>[3]</strong>: size_t
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function deletes the bytes at the end of the Ustr (Parameter[1])
 that are in the span (Parameter[2]) of the specificed length (parameter[2]).


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_sc_rtrim">ustr_sc_rtrim()</a>
<br>Returns: Success or failure<br>Type: int 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a pointer to a <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: struct Ustr **
</td></tr><tr><td>Parameter<strong>[2]</strong>: A pointer to a constant <a href="design.html">Ustr string</a>, containing trimming bytes<br>Type<strong>[2]</strong>: const struct Ustr *
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works as if you had called <a href="functions.html#ustr_sc_rtrim_chrs">ustr_sc_rtrim_chrs()</a> and passed
 <a href="functions.html#ustr_cstr">ustr_cstr()</a> and <a href="functions.html#ustr_len">ustr_len()</a> values of the <a href="design.html">Ustr string</a> (Parameter[2]).


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_sc_rtrim_cstr">ustr_sc_rtrim_cstr()</a>
<br>Returns: Success or failure<br>Type: int 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a pointer to a <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: struct Ustr **
</td></tr><tr><td>Parameter<strong>[2]</strong>: A pointer to a constant C-style string, containing trimming bytes<br>Type<strong>[2]</strong>: const char *
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works as if you had called <a href="functions.html#ustr_sc_rtrim_chrs">ustr_sc_rtrim_chrs()</a> and passed
 strlen() as the length.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_sc_trim_chrs">ustr_sc_trim_chrs()</a>
<br>Returns: Success or failure<br>Type: int 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a pointer to a <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: struct Ustr **
</td></tr><tr><td>Parameter<strong>[2]</strong>: Array of bytes, containing trimming data<br>Type<strong>[2]</strong>: const char *
</td></tr><tr><td>Parameter<strong>[3]</strong>: Length of byte data<br>Type<strong>[3]</strong>: size_t
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function deletes the bytes at the begining or end of the
 Ustr (Parameter[1]) that are in the span (Parameter[2]) of the specificed
 length (parameter[2]).

</td></tr><tr><td><strong>Note:</strong></td></tr><tr><td><p>
</p><p>  Calling this function is much more efficient than calling <a href="functions.html#ustr_sc_rtrim_chrs">ustr_sc_rtrim_chrs()</a>
 and then <a href="functions.html#ustr_sc_ltrim_chrs">ustr_sc_ltrim_chrs()</a>, as both ends are trimmed in a single pass.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_sc_trim">ustr_sc_trim()</a>
<br>Returns: Success or failure<br>Type: int 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a pointer to a <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: struct Ustr **
</td></tr><tr><td>Parameter<strong>[2]</strong>: A pointer to a constant <a href="design.html">Ustr string</a>, containing trimming bytes<br>Type<strong>[2]</strong>: const struct Ustr *
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works as if you had called <a href="functions.html#ustr_sc_trim_chrs">ustr_sc_trim_chrs()</a> and passed
 <a href="functions.html#ustr_cstr">ustr_cstr()</a> and <a href="functions.html#ustr_len">ustr_len()</a> values of the <a href="design.html">Ustr string</a> (Parameter[2]).


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_sc_trim_cstr">ustr_sc_trim_cstr()</a>
<br>Returns: Success or failure<br>Type: int 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a pointer to a <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: struct Ustr **
</td></tr><tr><td>Parameter<strong>[2]</strong>: A pointer to a constant C-style string, containing trimming bytes<br>Type<strong>[2]</strong>: const char *
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function works as if you had called <a href="functions.html#ustr_sc_trim_chrs">ustr_sc_trim_chrs()</a> and passed
 strlen() as the length.


</td></tr></table><table width="90%"><tr><td class="sect"><h2><a id="Adding%20binary%20data%20to%20a%20Ustr">Adding binary data to a Ustr</a></h2>
</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_add_b_uint16">ustr_add_b_uint16()</a>
<br>Returns: Success or failure<br>Type: int 
</td></tr><tr><td>Parameter<strong>[1]</strong>: Pointer to a pointer to a <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: struct Ustr **
</td></tr><tr><td>Parameter<strong>[2]</strong>: Binary value to add to the Ustr<br>Type<strong>[2]</strong>: uint_least16_t
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function adds a binary representation of a value (Parameter[2]) to the
 Ustr (Parameter[1]).


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_add_b_uint32">ustr_add_b_uint32()</a>
<br>Returns: Success or failure<br>Type: int 
</td></tr><tr><td>Parameter<strong>[1]</strong>: Pointer to a pointer to a <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: struct Ustr **
</td></tr><tr><td>Parameter<strong>[2]</strong>: Binary value to add to the Ustr<br>Type<strong>[2]</strong>: uint_least32_t
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function adds a binary representation of a value (Parameter[2]) to the
 Ustr (Parameter[1]).


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_add_b_uint64">ustr_add_b_uint64()</a>
<br>Returns: Success or failure<br>Type: int 
</td></tr><tr><td>Parameter<strong>[1]</strong>: Pointer to a pointer to a <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: struct Ustr **
</td></tr><tr><td>Parameter<strong>[2]</strong>: Binary value to add to the Ustr<br>Type<strong>[2]</strong>: uint_least64_t
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function adds a binary representation of a value (Parameter[2]) to the
 Ustr (Parameter[1]).


</td></tr></table><table width="90%"><tr><td class="sect"><h2><a id="Parsing%20binary%20data%20from%20a%20Ustr">Parsing binary data from a Ustr</a></h2>
</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_parse_b_uint16">ustr_parse_b_uint16()</a>
<br>Returns: uint_least16_t <br>Type: uint_least16_t 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[2]</strong>: Offset within string to start parsing at<br>Type<strong>[2]</strong>: size_t
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function parses a binary representation from a Ustr (Parameter[1]) 
 starting at the offset (Parameter[2]).


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_parse_b_uint32">ustr_parse_b_uint32()</a>
<br>Returns: uint_least32_t <br>Type: uint_least32_t 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[2]</strong>: Offset within string to start parsing at<br>Type<strong>[2]</strong>: size_t
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function parses a binary representation from a Ustr (Parameter[1]) 
 starting at the offset (Parameter[2]).


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_parse_b_uint64">ustr_parse_b_uint64()</a>
<br>Returns: uint_least64_t <br>Type: uint_least64_t 
</td></tr><tr><td>Parameter<strong>[1]</strong>: A pointer to a constant <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: const struct Ustr *
</td></tr><tr><td>Parameter<strong>[2]</strong>: Offset within string to start parsing at<br>Type<strong>[2]</strong>: size_t
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function parses a binary representation from a Ustr (Parameter[1]) 
 starting at the offset (Parameter[2]).


</td></tr></table><table width="90%"><tr><td class="sect"><h2><a id="Misc%2e%20functions">Misc. functions</a></h2>
</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_realloc">ustr_realloc()</a>
<br>Returns: Success or failure<br>Type: int
</td></tr><tr><td>Parameter<strong>[1]</strong>: Pointer to a pointer to a <a href="design.html">Ustr string</a><br>Type<strong>[1]</strong>: struct Ustr **
</td></tr><tr><td>Parameter<strong>[2]</strong>: Size of allocation<br>Type<strong>[2]</strong>: size_t
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function is re-sizes the Ustr to the specified size (Parameter[2]).
</p><p>  This is mostly used to shrink a sized Ustr that is now significantly
 smaller than it once was. Although this function can also grow a Ustr.

</td></tr><tr><td><strong>Note:</strong></td></tr><tr><td><p>
</p><p>  To have a size that isn't implied from the length the Ustr must store a size
 value as well as a length (<a href="functions.html#ustr_sized">ustr_sized()</a> must return <a href="constants.html#USTR_TRUE">USTR_TRUE</a>).


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_cntl_opt">ustr_cntl_opt()</a>
<br>Returns: Success or failure<br>Type: int 
</td></tr><tr><td>Parameter<strong>[1]</strong>: Optional value starting with USTR_CNTL_OPT_<br>Type<strong>[1]</strong>: int
</td></tr><tr><td>Parameter<strong>[2]</strong>: Arugments to option<br>Type<strong>[2]</strong>: ...
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This function views and/or changes global Ustr options, like whether ustr's
 have an implicit or explicit size (<a href="constants.html#USTR_CNTL_OPT_GET_HAS_SIZE">USTR_CNTL_OPT_GET_HAS_SIZE</a>).


</td></tr></table><table width="90%"><tr><td class="sect"><h2><a id="Simple%20Ustr%20pool%20API">Simple <a href="design.html#possibilities">Ustr pool</a> API</a></h2>
</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_pool_ll_make">ustr_pool_ll_make()</a>
<br>Returns: Pointer to a <a href="design.html#possibilities">Ustr pool</a> object<br>Type: struct Ustr_pool *
</td></tr><tr><td>Parameter<strong>[1]</strong>: Nothing<br>Type<strong>[1]</strong>: void
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This allocates a new pool using the &quot;linked list&quot; strategy, each allocation
 in the pool is added to a linked list ... and any allocations not freed
 directly are freed by the pool when it is cleared or freed.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_pool_make_subpool">ustr_pool_make_subpool()</a>
<br>Returns: Pointer to a <a href="design.html#possibilities">Ustr pool</a> object<br>Type: struct Ustr_pool *
</td></tr><tr><td>Parameter<strong>[1]</strong>: struct Ustr_pool *<br>Type<strong>[1]</strong>: struct Ustr_pool *
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This allocates a new pool as a child of the passed in pool (Parameter[1]),
 The pool can be freed and cleared independantly of the parent pool however
 free and clear operations on the parent pool are automatically applied to all
 child pools.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_pool_free">ustr_pool_free()</a>
<br>Returns: Nothing<br>Type: void
</td></tr><tr><td>Parameter<strong>[1]</strong>: Pointer to a <a href="design.html#possibilities">Ustr pool</a> object<br>Type<strong>[1]</strong>: struct Ustr_pool *
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This deallocates a pool, and all sub-pools.

</td></tr><tr><td><strong>Note:</strong></td></tr><tr><td><p>
</p><p>  This also operates on all sub-pools.


</td></tr></table><table width="80%"><tr><td class="obj">
<strong>Function: </strong> <a id="ustr_pool_clear">ustr_pool_clear()</a>
<br>Returns: Nothing<br>Type: void
</td></tr><tr><td>Parameter<strong>[1]</strong>: Pointer to a <a href="design.html#possibilities">Ustr pool</a> object<br>Type<strong>[1]</strong>: struct Ustr_pool *
</td></tr><tr><td><strong>Explanation:</strong></td></tr><tr><td><p>
</p><p>  This allows all the data in the pool to be reused, it may also free some/all
 of the data in the pool, from the pool API.

</td></tr><tr><td><strong>Note:</strong></td></tr><tr><td><p>
</p><p>  This also operates on all sub-pools.


</td></tr></table>
</body></html>